Phase 00: environment audit, corpus retrieval, mandate preservation
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
58 changed files +15,528 −0
added
.gitignore
+14 −0
@@ -0,0 +1,14 @@ | |||||
| 1 | +.env | ||||
| 2 | +*.pyc | ||||
| 3 | +__pycache__/ | ||||
| 4 | +.venv/ | ||||
| 5 | +paper/*.aux | ||||
| 6 | +paper/*.log | ||||
| 7 | +paper/*.out | ||||
| 8 | +paper/*.bbl | ||||
| 9 | +paper/*.blg | ||||
| 10 | +paper/*.fls | ||||
| 11 | +paper/*.fdb_latexmk | ||||
| 12 | +paper/*.synctex.gz | ||||
| 13 | +runs/**/raw_stream.jsonl | ||||
| 14 | +evidence/restricted/ | ||||
added
CLAUDE.md
+7 −0
@@ -0,0 +1,7 @@ | |||||
| 1 | +# WP29 — Protocol-Guided Autonomous Research with Claude Code (concise root instructions) | ||||
| 2 | + | ||||
| 3 | +This repository is UQO Working Paper 29. The **complete, immutable research mandate** is `protocol/WP29_FULL_MANDATE.md` (read it in full; this file is only a pointer). Phase log: `reports/phase_status.md`. Human interventions: `reports/interventions.csv`. Amendments to frozen designs: `protocol/amendments.csv`. | ||||
| 4 | + | ||||
| 5 | +Hard rules (from the mandate): never invent experiments, outputs, costs, screenshots or citations; live Claude Code runs are the only admissible experimental observations; hidden oracles live **outside** this repository (`~/wp29-oracles/`, never copied to executor nodes); executors run in `--bare` mode on cluster nodes with explicitly injected instructions; report null/negative results; do not submit or publish anything. | ||||
| 6 | + | ||||
| 7 | +Builder/controller/evaluator host = this laptop. Executor hosts = M3U96a, M3U96b, M4M64a, M4M64b (`~/wp29/`). Commands: see `Makefile` and `README.md`. | ||||
added
docs/claude-code-docs/cli-reference.md
+186 −0
@@ -0,0 +1,186 @@ | |||||
| 1 | +> ## Documentation Index | ||||
| 2 | +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt | ||||
| 3 | +> Use this file to discover all available pages before exploring further. | ||||
| 4 | + | ||||
| 5 | +# CLI reference | ||||
| 6 | + | ||||
| 7 | +> Complete reference for Claude Code command-line interface, including commands and flags. | ||||
| 8 | + | ||||
| 9 | +## CLI commands | ||||
| 10 | + | ||||
| 11 | +You can start sessions, pipe content, resume conversations, and manage updates with these commands: | ||||
| 12 | + | ||||
| 13 | +| Command | Description | Example | | ||||
| 14 | +| :- | :- | :- | | ||||
| 15 | +| `claude` | Start interactive session | `claude` | | ||||
| 16 | +| `claude "query"` | Start interactive session with initial prompt | `claude "explain this project"` | | ||||
| 17 | +| `claude -p "query"` | Query via SDK, then exit | `claude -p "explain this function"` | | ||||
| 18 | +| `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` | | ||||
| 19 | +| `claude -c` | Continue most recent conversation in current directory | `claude -c` | | ||||
| 20 | +| `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` | | ||||
| 21 | +| `claude -r "<session>" "query"` | Resume session by ID or name | `claude -r "auth-refactor" "Finish this PR"` | | ||||
| 22 | +| `claude update` | Update to latest version | `claude update` | | ||||
| 23 | +| `claude gateway` | Start the self-hosted [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) server, for administrators deploying SSO and policy in front of Claude Code on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. Requires `--config` pointing at a [`gateway.yaml`](https://code.claude.com/docs/en/claude-apps-gateway-config). | `claude gateway --config gateway.yaml` | | ||||
| 24 | +| `claude install [version]` | Install or reinstall the native binary. Accepts a version like `2.1.118`, or `stable` or `latest`. See [Install a specific version](https://code.claude.com/docs/en/setup.md#install-a-specific-version) | `claude install stable` | | ||||
| 25 | +| `claude auth login` | Sign in to your Anthropic account. Use `--email` to pre-fill your email address, `--sso` to force SSO authentication, and `--console` to sign in with Anthropic Console for API usage billing instead of a Claude subscription | `claude auth login --console` | | ||||
| 26 | +| `claude auth logout` | Log out from your Anthropic account | `claude auth logout` | | ||||
| 27 | +| `claude auth status` | Show authentication status as JSON. Use `--text` for human-readable output. Exits with code 0 if logged in, 1 if not. The JSON includes a `configDirectory` field naming the [configuration directory](https://code.claude.com/docs/en/claude-directory.md) the CLI uses. The field requires Claude Code v2.1.268 or later. The JSON's `authMethod` field is one of `none`, `claude.ai`, `oauth_token`, `api_key`, `api_key_helper`, or `third_party` | `claude auth status` | | ||||
| 28 | +| `claude agents` | Open [agent view](https://code.claude.com/docs/en/agent-view.md) to monitor and dispatch parallel background sessions. Use `--cwd <path>` to show only sessions started under that directory, or `--json` to print active sessions as a JSON array for scripting (`--json --all` also includes completed background sessions). Pass `--permission-mode`, `--model`, `--effort`, or `--agent` to set [defaults for dispatched sessions](https://code.claude.com/docs/en/agent-view.md#permission-mode-model-and-effort). Accepts `--settings`, `--add-dir`, `--plugin-dir`, and `--mcp-config` like the top-level `claude` command. Opening agent view requires an interactive terminal | `claude agents --json` | | ||||
| 29 | +| `claude attach <id\|name>` | Attach to a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell) in this terminal. Passing part of a running session's name in place of the ID requires Claude Code v2.1.290 or later | `claude attach 7c5dcf5d` | | ||||
| 30 | +| `claude auto-mode defaults` | Print the built-in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rules as JSON. Use `claude auto-mode config` to see your effective config with settings applied. `--label <prefix>` prints only the rules whose label starts with that prefix, matched case-insensitively. Requires Claude Code v2.1.208 or later | `claude auto-mode defaults --label 'Git Destructive'` | | ||||
| 31 | +| `claude auto-mode reset` | Restore the default [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) configuration by removing the `autoMode` section from your user settings file. Prompts for confirmation before writing; pass `-y`/`--yes` to skip the prompt. Rules from [managed settings](https://code.claude.com/docs/en/server-managed-settings.md) or the `--settings` flag still apply. Requires Claude Code v2.1.212 or later. See [Inspect the defaults and your effective config](https://code.claude.com/docs/en/auto-mode-config.md#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` | | ||||
| 32 | +| `claude daemon logs` | Follow the background-session [supervisor's](https://code.claude.com/docs/en/agent-view.md#the-supervisor-process) log file, `~/.claude/daemon.log`, printing new lines as they arrive until you press `Ctrl+C` | `claude daemon logs` | | ||||
| 33 | +| `claude daemon run` | Run the background-session [supervisor](https://code.claude.com/docs/en/agent-view.md#the-supervisor-process) in the foreground of this terminal, printing its log | `claude daemon run` | | ||||
| 34 | +| `claude daemon status` | Print the background-session [supervisor's](https://code.claude.com/docs/en/agent-view.md#the-supervisor-process) state, version, socket directory, and worker count for diagnostics. Exits 1 if the supervisor isn't running | `claude daemon status` | | ||||
| 35 | +| `claude daemon stop --any` | Stop the background-session [supervisor](https://code.claude.com/docs/en/agent-view.md#the-supervisor-process) and the sessions it hosts. Pass `--keep-workers` to leave background sessions running for the next supervisor to reconnect to. `--any` confirms stopping an on-demand supervisor, which is the default. Use this to recover from an [unresponsive supervisor](https://code.claude.com/docs/en/agent-view.md#agent-view-says-the-background-service-did-not-respond) | `claude daemon stop --any --keep-workers` | | ||||
| 36 | +| `claude doctor` | Print read-only installation and settings diagnostics from the terminal without starting a session, including install health, settings-file validation errors, and Remote Control eligibility. For the in-session setup checkup that can also apply fixes, run [`/doctor`](https://code.claude.com/docs/en/commands#all-commands) | `claude doctor` | | ||||
| 37 | +| `claude import [source]` | Start an interactive session that runs [`/import`](https://code.claude.com/docs/en/commands#all-commands) to bring configuration from other coding agents into Claude Code. Accepts the same `--dry-run` and `--yes` options as the command. Not available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. Also unavailable when you turn off [feature-flag fetching](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching). Requires Claude Code v2.1.213 or later | `claude import codex --dry-run` | | ||||
| 38 | +| `claude logs <id\|name>` | Print recent output from a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell). Passing part of a session's name in place of the ID requires Claude Code v2.1.290 or later | `claude logs 7c5dcf5d` | | ||||
| 39 | +| `claude mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp.md). | | ||||
| 40 | +| `claude mcp login <name>` | Run a configured MCP server's OAuth flow without opening the interactive `/mcp` panel. Works for HTTP, SSE, and claude.ai connector servers. Add `--no-browser` over SSH to print the authorization URL instead of opening a browser. For an HTTP or SSE server, paste the redirect URL back at the prompt. For a claude.ai connector, see [Authorize a connector again from your shell](https://code.claude.com/docs/en/remote-control.md#authorize-a-connector-again-from-your-shell). See [Authenticate from the command line](https://code.claude.com/docs/en/mcp.md#authenticate-from-the-command-line) | `claude mcp login sentry` | | ||||
| 41 | +| `claude mcp logout <name>` | Clear stored OAuth credentials for an MCP server | `claude mcp logout sentry` | | ||||
| 42 | +| `claude plugin` | Manage Claude Code [plugins](https://code.claude.com/docs/en/plugins/overview.md). Alias: `claude plugins`. See [plugin reference](https://code.claude.com/docs/en/plugins/cli-reference.md#claude-plugin-commands) for subcommands | `claude plugin install code-review@claude-plugins-official` | | ||||
| 43 | +| `claude purge [path]` | Delete all local Claude Code state for a project: transcripts, task lists, debug logs, file-edit history, prompt history lines, and the project's entry in `~/.claude.json`. Omit `[path]` to pick from an interactive list. Flags: `--dry-run` to preview, `-y`/`--yes` to skip confirmation, `-i`/`--interactive` to confirm each item, `--all` for every project. See [Clear local data](https://code.claude.com/docs/en/claude-directory.md#clear-local-data) | `claude purge ~/work/repo --dry-run` | | ||||
| 44 | +| `claude remote-control` | Start a [Remote Control](https://code.claude.com/docs/en/remote-control.md) server to control Claude Code from Claude.ai or the Claude app. Runs in server mode (no local interactive session). See [Server mode flags](https://code.claude.com/docs/en/remote-control.md#start-a-remote-control-session). After you stop the server, you can bring back the sessions it was serving. See [Resume sessions after stopping the server](https://code.claude.com/docs/en/remote-control.md#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` | | ||||
| 45 | +| `claude respawn <id>` | Restart a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell), running or stopped, with its conversation intact. Use `--all` to restart every running session, e.g. to pick up an updated Claude Code binary | `claude respawn 7c5dcf5d` | | ||||
| 46 | +| `claude rm <id>` | Remove a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell) from the list. When the removal is [refused over the session's worktree](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) and a second `claude rm` can resolve it, the refusal prints the exact flag and value to pass: `--discard-unpushed <commit>@<worktree-id>` discards a worktree that has unpushed commits along with those commits, and `--force-remove-worktree <worktree-id>` deletes a worktree directory that git or the `WorktreeRemove` hook couldn't remove. `--discard-unpushed` requires Claude Code v2.1.260 or later, and `--force-remove-worktree` requires v2.1.268 or later. The conversation transcript stays on your local machine, available through `claude --resume` | `claude rm 7c5dcf5d` | | ||||
| 47 | +| `claude self-hosted-runner` | Start a runner process that registers this machine or container with a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) and hosts Claude Code cloud sessions on your infrastructure. Run `claude self-hosted-runner setup` for a guided operator walkthrough, `claude self-hosted-runner doctor` to [diagnose a deployed runner](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#troubleshooting), and `claude self-hosted-runner orchestrator` to spawn [on-demand runners](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#on-demand-runners). Requires Claude Code v2.1.224 or later | `claude self-hosted-runner setup` | | ||||
| 48 | +| `claude setup-token` | Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it. Requires a Claude subscription. See [Generate a long-lived token](https://code.claude.com/docs/en/authentication.md#generate-a-long-lived-token) | `claude setup-token` | | ||||
| 49 | +| `claude stop <id>` | Stop a [background session](https://code.claude.com/docs/en/agent-view.md#manage-sessions-from-the-shell). Also accepts `claude kill` | `claude stop 7c5dcf5d` | | ||||
| 50 | +| `claude ultrareview [target]` | Run [ultrareview](https://code.claude.com/docs/en/ultrareview.md#run-ultrareview-non-interactively) non-interactively. Prints findings to stdout and exits 0 on success or 1 on failure. Use `--json` for the raw payload and `--timeout <minutes>` to override the 45-minute default. Use `--post` on a `github.com` pull request target to post the finished findings to the PR as one plain comment from your GitHub account. `--no-post` is the default. `--post` and `--no-post` require Claude Code v2.1.227 or later. See [Post findings to the pull request](https://code.claude.com/docs/en/ultrareview.md#post-findings-to-the-pull-request) | `claude ultrareview 1234 --json` | | ||||
| 51 | + | ||||
| 52 | +If you mistype a subcommand, Claude Code suggests the closest match and exits without starting a session. For example, `claude udpate` prints `Did you mean claude update?`. | ||||
| 53 | + | ||||
| 54 | +`claude --dangerously-skip-permissions daemon <subcommand>` runs the `daemon` subcommand, so the subcommand works when `claude` is aliased to include the flag. Only a leading `--dangerously-skip-permissions` or `--allow-dangerously-skip-permissions` routes to `daemon` this way; with any other flag ahead of `daemon`, the subcommand doesn't run. | ||||
| 55 | + | ||||
| 56 | +## CLI flags | ||||
| 57 | + | ||||
| 58 | +Customize Claude Code's behavior with these command-line flags. `claude --help` does not list every flag, so a flag's absence from `--help` does not mean it is unavailable. | ||||
| 59 | + | ||||
| 60 | +| Flag | Description | Example | | ||||
| 61 | +| :- | :- | :- | | ||||
| 62 | +| `--add-dir` | Add additional working directories for Claude to read and edit files. Grants file access; Claude Code [doesn't discover](https://code.claude.com/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration) most `.claude/` configuration from these directories. Validates that each path exists as a directory. You can't add most [network paths](https://code.claude.com/docs/en/errors.md#working-directory-is-a-network-path), such as `\\server\share`. To persist these directories across sessions, set [`permissions.additionalDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-additionaldirectories) in settings | `claude --add-dir ../apps ../lib` | | ||||
| 63 | +| `--advisor <model>` | Enable the server-side [advisor tool](https://code.claude.com/docs/en/advisor.md) for this session with a model alias, `fable`, `opus`, or `sonnet`, or a full model ID. Takes precedence over the `advisorModel` setting for the session. `fable` requires [Fable access](https://code.claude.com/docs/en/advisor.md#choose-an-advisor-model) | `claude --advisor opus` | | ||||
| 64 | +| `--agent` | Specify an agent for the current session (overrides the `agent` setting) | `claude --agent my-custom-agent` | | ||||
| 65 | +| `--agents` | Define custom subagents dynamically via JSON. Accepts the [fields listed for CLI-defined subagents](https://code.claude.com/docs/en/sub-agents.md#choose-the-subagent-scope). With `--print`, the value can instead be the path to a JSON file holding the object; the file form requires Claude Code v2.1.281 or later. Claude Code validates the value at startup and exits on an invalid one; see [`Invalid --agents configuration`](https://code.claude.com/docs/en/errors#invalid-agents-configuration) for the message and for the flags and environment variable that skip the validation. Validation requires Claude Code v2.1.242 or later | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` | | ||||
| 66 | +| `--allow-dangerously-skip-permissions` | Add `bypassPermissions` to the `Shift+Tab` mode cycle without starting in it. Lets you begin in a different mode like `plan` and switch to `bypassPermissions` later. See [permission modes](https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` | | ||||
| 67 | +| `--allowedTools`, `--allowed-tools` | Tools that execute without prompting for permission, apart from reads from [network paths](https://code.claude.com/docs/en/permissions.md#network-paths). See [permission rule syntax](https://code.claude.com/docs/en/settings-reference.md#permission-rule-syntax) for pattern matching. To restrict which tools are available, use `--tools` instead. If you name one of the [task-tracking tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability) here, Claude Code also opts the session in | `"Bash(git log *)" "Bash(git diff *)" "Read"` | | ||||
| 68 | +| `--append-subagent-system-prompt` | Append custom text to the end of every [subagent](https://code.claude.com/docs/en/sub-agents.md)'s system prompt, nested subagents included, apart from a [forked subagent](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), which reuses the conversation's own prompt. Only applies in non-interactive mode with `-p`. Requires Claude Code v2.1.205 or later | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` | | ||||
| 69 | +| `--append-subagent-system-prompt-file` | Load text from a file and append it to [subagent](https://code.claude.com/docs/en/sub-agents.md) system prompts. An alternative to `--append-subagent-system-prompt` for text too long to pass on the command line. The two flags can't be combined. Only applies in non-interactive mode with `-p`. Requires Claude Code v2.1.261 or later | `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` | | ||||
| 70 | +| `--append-system-prompt` | Append custom text to the end of the default system prompt | `claude --append-system-prompt "Always use TypeScript"` | | ||||
| 71 | +| `--append-system-prompt-file` | Load additional system prompt text from a file and append to the default prompt | `claude --append-system-prompt-file ./extra-rules.txt` | | ||||
| 72 | +| `--autocompact <auto\|tokens>` | Set the [auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window) for this session without changing your saved settings. Accepts the same values as `/autocompact`; that section covers the value forms and what overrides the flag. Requires Claude Code v2.1.221 or later | `claude --autocompact 500k` | | ||||
| 73 | +| `--ax-screen-reader` | Render screen-reader friendly output: flat text without decorative borders or animations. Forces the classic renderer, so the [`tui`](https://code.claude.com/docs/en/settings-reference#tui) setting has no effect; attached [background sessions](https://code.claude.com/docs/en/agent-view.md) still render fullscreen. Takes precedence over [`CLAUDE_AX_SCREEN_READER`](https://code.claude.com/docs/en/env-vars) and the [`axScreenReader`](https://code.claude.com/docs/en/settings-reference#axscreenreader) setting. Requires Claude Code v2.1.181 or later | `claude --ax-screen-reader` | | ||||
| 74 | +| `--bare` | Minimal mode: skip auto-discovery of hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory, and CLAUDE.md so scripted calls start faster. Skills in a directory you pass with `--add-dir` still load. Claude has access to Bash, file read, and file edit tools. Sets [`CLAUDE_CODE_SIMPLE`](https://code.claude.com/docs/en/env-vars). See [bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode) | `claude --bare -p "query"` | | ||||
| 75 | +| `--betas` | Beta headers to include in API requests (API key users only) | `claude --betas interleaved-thinking` | | ||||
| 76 | +| `--bg`, `--background` | Start the session as a [background agent](https://code.claude.com/docs/en/agent-view.md) and return immediately. Prints the session ID and management commands. Combine with `--exec` to run a shell command as a background job instead of a Claude session, or with `--agent` to run a specific subagent. Checks [workspace trust](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the directory before it starts. Can't be combined with `-p`/`--print`; see the [error reference](https://code.claude.com/docs/en/errors.md#command-line-errors) | `claude --bg "investigate the flaky test"` | | ||||
| 77 | +| `--channels` | (Research preview) MCP servers whose [channel](https://code.claude.com/docs/en/channels.md) notifications Claude should listen for in this session. Space-separated list of `plugin:<name>@<marketplace>` entries. Requires Anthropic authentication through claude.ai or a Console API key | `claude --channels plugin:my-notifier@my-marketplace` | | ||||
| 78 | +| `--chrome` | Enable [Chrome browser integration](https://code.claude.com/docs/en/chrome.md) for web automation and testing | `claude --chrome` | | ||||
| 79 | +| `--cloud` | With a task description, create a new [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md). With a session ID (`session_...` or `cse_...`) or a claude.ai/code URL, queue a message into that existing session instead, with `-p`. See [send a follow-up message](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-follow-ups-from-the-cli). | `claude --cloud "Fix the login bug"` | | ||||
| 80 | +| `--continue`, `-c` | Load the most recent conversation in the current directory, including a [background session that has finished](https://code.claude.com/docs/en/sessions.md#where-the-session-picker-looks); opening finished background sessions requires Claude Code v2.1.257 or later. Skips sessions created with `claude -p` or the Agent SDK, and sessions whose first prompt was `/loop`. `claude -p --continue` includes `-p`, SDK, and `/loop` sessions. Includes sessions that added this directory with `/add-dir` | `claude --continue` | | ||||
| 81 | +| `--dangerously-load-development-channels` | Enable [channels](https://code.claude.com/docs/en/channels-reference.md#test-during-the-research-preview) that are not on the approved allowlist, for local development. Accepts `plugin:<name>@<marketplace>` and `server:<name>` entries. Prompts for confirmation, so it takes effect in interactive sessions. With `-p`, Claude Code ignores the flag | `claude --dangerously-load-development-channels server:webhook` | | ||||
| 82 | +| `--dangerously-skip-permissions` | Skip permission prompts. Equivalent to `--permission-mode bypassPermissions`. See [permission modes](https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) for what this does and does not skip. For sessions started with `--bg`, the mode [persists when the supervisor restarts the session](https://code.claude.com/docs/en/agent-view.md#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` | | ||||
| 83 | +| `--debug` | Enable debug mode with optional category filtering, such as `--debug='mcp,startup'` or `--debug='!mcp'`. The filter binds only in the `=` form; a space-separated filter enables debug mode without filtering | `claude --debug='mcp,startup'` | | ||||
| 84 | +| `--debug-file <path>` | Write debug logs to a specific file path. Implicitly enables debug mode. Takes precedence over `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` | | ||||
| 85 | +| `--desktop` | Open the [Claude Desktop app](https://code.claude.com/docs/en/desktop.md) on the current directory and exit without starting a session in the terminal. Add `--continue`, or `--resume` with a session ID, to [open that session in Desktop](https://code.claude.com/docs/en/desktop.md#coming-from-the-cli) instead. `--resume` here takes only a session ID, not a name or transcript path. Takes no prompt and no other flags except `--verbose` and the `--debug` flags, since the app starts the session itself. Available on macOS and x64 Windows when you're signed in with a Claude subscription. Requires Claude Code v2.1.285 or later | `claude --desktop` | | ||||
| 86 | +| `--disable-slash-commands` | Disable all skills and commands for this session | `claude --disable-slash-commands` | | ||||
| 87 | +| `--disallowedTools`, `--disallowed-tools` | Deny rules. A bare tool name removes the matching tools from Claude's context: `"Edit"` removes Edit, `"*"` removes every tool, and `"mcp__*"` removes every MCP tool. A scoped rule such as `Bash(rm *)` leaves the tool available and denies only calls that match [as written](https://code.claude.com/docs/en/permissions.md#bash-rule-limits). A rule naming [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) can't remove it while any other tool remains | `"Bash(git log *)" "Bash(git diff *)" "Edit"` | | ||||
| 88 | +| `--effort` | Set the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) for the current session. Options: `low`, `medium`, `high`, `xhigh`, `max`, or `ultracode`. Available levels depend on the model. `ultracode` requests `xhigh` effort with [ultracode](https://code.claude.com/docs/en/workflows.md#let-claude-decide-with-ultracode) turned on, and requires Claude Code v2.1.203 or later. Overrides the [`modelSettings`](https://code.claude.com/docs/en/settings-reference#modelsettings) and [`effortLevel`](https://code.claude.com/docs/en/settings-reference#effortlevel) settings for this session and does not persist | `claude --effort high` | | ||||
| 89 | +| `--enable-auto-mode` | Removed in v2.1.111. Auto mode is now in the `Shift+Tab` cycle by default; use `--permission-mode auto` to start in it | `claude --permission-mode auto` | | ||||
| 90 | +| `--environment <environment-id>` | Create a new cloud session that runs on the [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) with the given ID. Environment IDs start with `ccpool_`. See [`--environment` dispatch behavior](https://code.claude.com/docs/en/self-hosted-environments-testing#environment-dispatch-behavior) for dispatch behavior and the flag combinations it rejects. Requires Claude Code v2.1.224 or later | `claude -p "Fix the login bug" --environment ccpool_abc123` | | ||||
| 91 | +| `--exclude-dynamic-system-prompt-sections` | Move per-user context, such as the auto memory location, out of the system prompt and into the first user message. Improves prompt-cache reuse across different users and machines running the same task. Only applies with the default system prompt; ignored when `--system-prompt` or `--system-prompt-file` is set. Use with `-p` for scripted, multi-user workloads | `claude -p --exclude-dynamic-system-prompt-sections "query"` | | ||||
| 92 | +| `--exec` | Run a shell command as a PTY-backed background job instead of starting a Claude session. Use with `--bg` to launch from the shell | `claude --bg --exec 'pytest -x'` | | ||||
| 93 | +| `--fallback-model` | Enable automatic fallback to the specified model(s) when the primary model is overloaded or not available, for example a retired model. Accepts a comma-separated list tried in order. See [Fallback model chains](https://code.claude.com/docs/en/model-config.md#fallback-model-chains). To persist a chain across sessions, use the [`fallbackModel` setting](https://code.claude.com/docs/en/settings-reference#fallbackmodel), which this flag overrides | `claude --fallback-model sonnet,haiku` | | ||||
| 94 | +| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` | | ||||
| 95 | +| `--forward-subagent-text` | Emit [subagent](https://code.claude.com/docs/en/sub-agents.md) text and thinking blocks in the output stream as `assistant` and `user` messages with `parent_tool_use_id` set, so you can reconstruct each subagent's transcript. Without this flag, Claude Code omits the text and thinking blocks of a subagent that runs in the [foreground](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background). Requires `--print` and `--output-format stream-json`. For nested subagents, forked skills, and the version each needs, see [Follow subagent messages](https://code.claude.com/docs/en/headless.md#follow-subagent-messages). The [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](https://code.claude.com/docs/en/env-vars) environment variable enables the same behavior. Requires Claude Code v2.1.211 or later | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` | | ||||
| 96 | +| `--from-pr` | Open the session picker filtered to sessions linked to a specific pull request. Accepts a PR number, a GitHub or GitHub Enterprise PR URL, a GitLab merge request URL, or a Bitbucket pull request URL. Sessions are linked automatically when Claude creates the pull request | `claude --from-pr 123` | | ||||
| 97 | +| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` | | ||||
| 98 | +| `--init` | Run [Setup hooks](https://code.claude.com/docs/en/hooks.md#setup) with the `init` matcher before the session (print mode only) | `claude -p --init "query"` | | ||||
| 99 | +| `--init-only` | Run [Setup](https://code.claude.com/docs/en/hooks.md#setup) and `SessionStart` hooks, then exit without starting a conversation | `claude --init-only` | | ||||
| 100 | +| `--include-hook-events` | Include hook lifecycle events in the output stream. `SessionStart` and `Setup` hook events are always included and don't need this flag. Some hook events, such as `Notification`, `SessionEnd`, `PreCompact`, and `PostCompact`, never produce a `hook_started` event, even with this flag. For those events, Claude Code still emits `hook_progress` while a command hook that runs for more than a second produces output, and emits `hook_response` only when a [hook that runs in the background](https://code.claude.com/docs/en/hooks.md#run-hooks-in-the-background) finishes. Requires `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` | | ||||
| 101 | +| `--include-partial-messages` | Include partial streaming events in output. Requires `--print` and `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` | | ||||
| 102 | +| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` | | ||||
| 103 | +| `--json-schema` | Get validated JSON output matching a JSON Schema after the agent completes its workflow (print mode only). See [structured outputs](https://code.claude.com/docs/en/agent-sdk/structured-outputs.md). Claude Code exits with an error on an invalid schema and accepts the `format` keyword as an annotation without client-side validation | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` | | ||||
| 104 | +| `--maintenance` | Run [Setup hooks](https://code.claude.com/docs/en/hooks.md#setup) with the `maintenance` matcher before the session (print mode only) | `claude -p --maintenance "query"` | | ||||
| 105 | +| `--max-budget-usd` | Stop the run once estimated spend on API calls reaches this amount (print mode only). Claude Code checks the cap against its [client-side cost estimate](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md#estimates-not-billing), which can differ from your bill. Spend from [subagents](https://code.claude.com/docs/en/sub-agents.md) counts toward the cap. Spend can pass the cap, so [leave headroom](https://code.claude.com/docs/en/agent-sdk/agent-loop.md#budget-headroom). When you return to a conversation with `--continue` or `--resume`, totals [restored from earlier runs](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md#accumulate-costs-across-multiple-calls) don't count toward it. Once spend reaches the cap, spawning another subagent fails with `Budget limit reached`, and Claude Code stops background subagents that are still running; the cap-enforcement behaviors require Claude Code v2.1.217 or later | `claude -p --max-budget-usd 5.00 "query"` | | ||||
| 106 | +| `--max-turns` | Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default. With `--input-format stream-json`, a message still queued when the limit ends a turn stays queued and starts a new turn with its own limit | `claude -p --max-turns 3 "query"` | | ||||
| 107 | +| `--mcp-config` | Load MCP servers from JSON files or strings (space-separated). When you pass this flag with `-p`, Claude Code waits for still-pending servers to connect before running the first turn, up to the [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) startup timeout, 30 seconds by default; a server with a [cached tool list](https://code.claude.com/docs/en/mcp.md#managing-your-servers) skips the wait and connects on first use. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#connection-timing), a shorter wait applies instead. The wait requires Claude Code v2.1.221 or later | `claude --mcp-config ./mcp.json` | | ||||
| 108 | +| `--model` | Sets the model for the current session with a [model alias](https://code.claude.com/docs/en/model-config.md#model-aliases) such as `sonnet`, `opus`, `haiku`, or `fable`, or a model's full name. Overrides the [`model`](https://code.claude.com/docs/en/settings-reference#model) setting and [`ANTHROPIC_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables) | `claude --model claude-sonnet-5` | | ||||
| 109 | +| `--name`, `-n` | Set a display name for the session, shown in `/resume` and the terminal title. You can resume a named session with `claude --resume <name>`. [`/rename`](https://code.claude.com/docs/en/commands) changes the name mid-session and also shows it on the prompt bar | `claude -n "my-feature-work"` | | ||||
| 110 | +| `--no-chrome` | Disable [Chrome browser integration](https://code.claude.com/docs/en/chrome.md) for this session | `claude --no-chrome` | | ||||
| 111 | +| `--no-session-persistence` | Disable session persistence so sessions are not saved to disk and cannot be resumed. Print mode only. The [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](https://code.claude.com/docs/en/env-vars) environment variable does the same in any mode | `claude -p --no-session-persistence "query"` | | ||||
| 112 | +| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` | | ||||
| 113 | +| `--permission-mode` | Begin in a specified [permission mode](https://code.claude.com/docs/en/permission-modes.md). Accepts `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`, or `manual` as an alias for `default`. The `manual` alias selects the permission mode the UI labels Manual and requires Claude Code v2.1.200 or later; `claude --help` lists it in place of `default`, and both values work. Overrides `defaultMode` from settings files. Without this flag or `--dangerously-skip-permissions`, a new session starts in the permission mode described in [which permission mode a session starts in](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in), which also covers what a `-p` run starts in | `claude --permission-mode plan` | | ||||
| 114 | +| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode. Pass the full name, such as `mcp__<server>__<tool>`, of a tool on an MCP server that the run loads. Claude Code waits for that tool's MCP server to connect before running the first turn, up to the [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) startup timeout, 30 seconds by default. The prompt tool can't approve an MCP tool marked as [requiring user interaction](https://code.claude.com/docs/en/mcp.md#require-approval-for-a-specific-tool): Claude Code converts an `allow` result for one to a deny. This restriction requires Claude Code v2.1.199 or later | `claude -p --mcp-config ./mcp.json --permission-prompt-tool mcp__permissions__approve "query"` | | ||||
| 115 | +| `--permission-prompts` | Set who answers permission prompts in print mode. With the default `host`, Claude Code sends them to the Agent SDK host or the `--permission-prompt-tool` tool. Pass `none` when nobody can answer, and Claude Code denies them instead. See [Turn off permission prompts in unattended runs](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs). Requires Claude Code v2.1.259 or later | `claude -p --permission-prompts none "query"` | | ||||
| 116 | +| `--plugin-dir` | Load a plugin from a directory or `.zip` archive, or several from a [folder of plugins](https://code.claude.com/docs/en/plugins/create.md#load-a-directory-or-archive-for-one-session), for this session only. Each flag takes one path. Repeat the flag for more paths: `--plugin-dir A --plugin-dir B.zip`. Passing a folder of plugins requires Claude Code v2.1.265 or later | `claude --plugin-dir ./my-plugin` | | ||||
| 117 | +| `--plugin-url` | Fetch a plugin `.zip` archive from a URL for this session only. Repeat the flag for multiple plugins, or pass space-separated URLs in a single quoted value | `claude --plugin-url https://example.com/plugin.zip` | | ||||
| 118 | +| `--print`, `-p` | Print response without interactive mode (see [Agent SDK documentation](https://code.claude.com/docs/en/agent-sdk/overview.md) for programmatic usage details). For `--resume` on a background session that is still running, see [Resume a running background session](https://code.claude.com/docs/en/sessions.md#resume-a-running-background-session) | `claude -p "query"` | | ||||
| 119 | +| `--prompt-suggestions` | Emit a `prompt_suggestion` message with a predicted next user prompt after each turn that generates one; very short conversations can produce none. Requires `--print`, `--output-format stream-json`, and `--verbose`. See [Prompt suggestions](https://code.claude.com/docs/en/interactive-mode.md#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` | | ||||
| 120 | +| `--ref <branch>` | With `--environment`, base the new session's checkout on a named ref instead of local `HEAD` | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` | | ||||
| 121 | +| `--remote` | Deprecated alias for `--cloud`, including the existing-session form | `claude --remote "Fix the login bug"` | | ||||
| 122 | +| `--remote-control`, `--rc` | Start an interactive session with [Remote Control](https://code.claude.com/docs/en/remote-control.md#start-a-remote-control-session) enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | `claude --remote-control "My Project"` | | ||||
| 123 | +| `--remote-control-session-name-prefix <prefix>` | Prefix for auto-generated [Remote Control](https://code.claude.com/docs/en/remote-control.md) session names when no explicit name is set. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. Set `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` for the same effect | `claude remote-control --remote-control-session-name-prefix dev-box` | | ||||
| 124 | +| `--replay-user-messages` | Re-emit user messages from stdin back on stdout for acknowledgment. Requires `--input-format stream-json` and `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` | | ||||
| 125 | +| `--restricted` | Start in restricted mode. Use it when an evaluation harness drives `claude` on a shared machine and Claude Code must not run commands or read that machine's user and project settings. Claude Code removes the built-in tools that run commands or code, and WebFetch, unless you name them individually in `--tools`, not through the `default` preset. It also confines the built-in file tools to the [working directories](https://code.claude.com/docs/en/permissions.md#working-directories), loads only [managed settings](https://code.claude.com/docs/en/managed-settings.md) and `--settings`, refuses [`bypassPermissions`](https://code.claude.com/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode), and [refuses to create cloud sessions](https://code.claude.com/docs/en/errors.md#cloud-sessions-cannot-be-created-from-a-restricted-session). Requires Claude Code v2.1.248 or later | `claude --restricted -p "query"` | | ||||
| 126 | +| `--resume`, `-r` | Resume a specific session by ID or name, or show an interactive picker to choose a session. In place of an ID, you can pass the absolute path to a session's `.jsonl` [transcript file](https://code.claude.com/docs/en/sessions.md#where-transcripts-are-stored). The picker and name search include sessions that added this directory with `/add-dir`. When you pass a session ID, Claude Code searches the current project directory and its git worktrees, then every other project on this machine. Before v2.1.223, the ID search covered only the current project directory and its git worktrees. [Background sessions](https://code.claude.com/docs/en/agent-view.md) appear in the picker marked with `bg`. Resuming one that is still running [opens that session](https://code.claude.com/docs/en/sessions.md#resume-a-running-background-session) in this terminal through `claude attach`, and a prompt you pass on the command line goes to it as its next turn. Before v2.1.285, Claude Code refused and printed the `claude attach` command to run instead | `claude --resume auth-refactor` | | ||||
| 127 | +| `--safe-mode` | Start with all customizations disabled to troubleshoot a broken configuration: CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, workflows, custom themes, custom keybindings, status line and file-suggestion commands, LSP servers, and auto memory do not load. Authentication, model selection, built-in tools, and permissions work normally, which differs from [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode). Managed settings policy still applies, including policy-configured hooks, status line, and file-suggestion commands; managed plugins, managed skills, managed CLAUDE.md, and policy-configured MCP servers do not. Useful for checking whether a customization is what triggers [automatic model fallback](https://code.claude.com/docs/en/model-config.md#automatic-model-fallback). Sets [`CLAUDE_CODE_SAFE_MODE`](https://code.claude.com/docs/en/env-vars) | `claude --safe-mode` | | ||||
| 128 | +| `--session-id` | Use a specific session ID for the conversation (must be a valid UUID) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` | | ||||
| 129 | +| `--setting-sources` | Comma-separated list of setting sources to load (`user`, `project`, `local`). See [agent view](https://code.claude.com/docs/en/agent-view.md#what-carries-over-when-you-background) and [agent teams](https://code.claude.com/docs/en/agent-teams.md#context-and-communication) for the sessions you start from this one that inherit the list | `claude --setting-sources user,project` | | ||||
| 130 | +| `--settings` | Path to a settings JSON file or an inline JSON string. Values you set here override the same keys in your `settings.json` files for this session. Keys you omit keep their file-based values. The file must be a regular file no larger than 2 MiB. See [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) | `claude --settings ./settings.json` | | ||||
| 131 | +| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations. See [Exclusive control with managed-mcp.json](https://code.claude.com/docs/en/managed-mcp.md#exclusive-control-with-managed-mcp-json) for what the flag does under a managed MCP file | `claude --strict-mcp-config --mcp-config ./mcp.json` | | ||||
| 132 | +| `--system-prompt` | Replace the entire system prompt with custom text | `claude --system-prompt "You are a Python expert"` | | ||||
| 133 | +| `--system-prompt-file` | Load system prompt from a file, replacing the default prompt | `claude --system-prompt-file ./custom-prompt.txt` | | ||||
| 134 | +| `--system-prompt-snapshot` | Pass `off` to rebuild the system prompt on every request instead of reusing the prompt [recorded on the conversation's first request](#system-prompt-flags-in-resumed-conversations), for example while you iterate on `--append-system-prompt` text across `--continue` runs. Requires Claude Code v2.1.257 or later | `claude --system-prompt-snapshot off` | | ||||
| 135 | +| `--teleport` | Resume a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) in your local terminal | `claude --teleport` | | ||||
| 136 | +| `--teammate-mode` | Set how [agent team](https://code.claude.com/docs/en/agent-teams.md) teammates display: `in-process` (default), `auto`, `tmux`, or `iterm2`. Overrides the [`teammateMode`](https://code.claude.com/docs/en/settings-reference#teammatemode) setting for this session. See [Choose a display mode](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) | `claude --teammate-mode auto` | | ||||
| 137 | +| `--tmux` | Create a tmux session for the worktree. Requires `--worktree`. Uses iTerm2 native panes when available; pass `--tmux=classic` for traditional tmux | `claude -w feature-auth --tmux` | | ||||
| 138 | +| `--tools` | Restrict which built-in tools Claude can use. Use `""` to disable all, `"default"` for the default set, or tool names like `"Bash,Edit,Read"`. On macOS, Linux, and WSL, the default set leaves out `Glob` and `Grep`, as described under [Glob tool behavior](https://code.claude.com/docs/en/tools-reference.md#glob-tool-behavior). If you name one of the [task-tracking tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability) here, Claude Code also opts the session in. The flag doesn't affect MCP tools; to deny those too, use `--disallowedTools "mcp__*"`. A list that omits [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) doesn't remove it; `""` removes it only when no MCP tools remain | `claude --tools "Bash,Edit,Read"` | | ||||
| 139 | +| `--verbose` | Enable verbose logging, shows full turn-by-turn output. Overrides the [`viewMode`](https://code.claude.com/docs/en/settings-reference#viewmode) setting for this session | `claude --verbose` | | ||||
| 140 | +| `--version`, `-v` | Output the version number | `claude -v` | | ||||
| 141 | +| `--worktree`, `-w` | Start Claude in an isolated [git worktree](https://code.claude.com/docs/en/worktrees.md) at `<repo>/.claude/worktrees/<name>`. If you don't give a name, Claude Code generates one. Pass `#<number>`, a GitHub pull request URL, or a GitLab merge request URL to [fetch that PR or MR from `origin` and branch the worktree from it](https://code.claude.com/docs/en/worktrees#branch-from-a-pull-request). Branching from a GitLab merge request requires Claude Code v2.1.233 or later | `claude -w feature-auth` | | ||||
| 142 | + | ||||
| 143 | +### System prompt flags | ||||
| 144 | + | ||||
| 145 | +Claude Code provides five flags for customizing the system prompt. Four set its text, and with `--system-prompt-snapshot` you control whether a conversation keeps the text it started with. All five work in both interactive and non-interactive modes. | ||||
| 146 | + | ||||
| 147 | +| Flag | Behavior | Example | | ||||
| 148 | +| :- | :- | :- | | ||||
| 149 | +| `--system-prompt` | Replaces the entire default prompt | `claude --system-prompt "You are a Python expert"` | | ||||
| 150 | +| `--system-prompt-file` | Replaces with file contents | `claude --system-prompt-file ./prompts/review.txt` | | ||||
| 151 | +| `--append-system-prompt` | Appends to the default prompt | `claude --append-system-prompt "Always use TypeScript"` | | ||||
| 152 | +| `--append-system-prompt-file` | Appends file contents to the default prompt | `claude --append-system-prompt-file ./style-rules.txt` | | ||||
| 153 | +| `--system-prompt-snapshot` | With `off`, rebuilds the prompt on every request. With `on`, the default, reuses a recorded prompt where [recording applies](#system-prompt-flags-in-resumed-conversations) | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` | | ||||
| 154 | + | ||||
| 155 | +You can combine these flags. To replace the default prompt and still append your own text, pass `--append-system-prompt` or `--append-system-prompt-file` together with `--system-prompt` or `--system-prompt-file`. With Claude Code v2.1.283 or later, you can also pass a flag together with its own file form, such as `--append-system-prompt` with `--append-system-prompt-file`, and Claude Code uses both. | ||||
| 156 | + | ||||
| 157 | +For example, run the following in your shell to append both a style guide from a file and one extra instruction: | ||||
| 158 | + | ||||
| 159 | +```bash theme={null} | ||||
| 160 | +claude -p --append-system-prompt-file ./style.md --append-system-prompt "Always reply in French" "Summarize README.md" | ||||
| 161 | +``` | ||||
| 162 | + | ||||
| 163 | +Claude receives the default system prompt followed by the contents of `style.md`, a blank line, and then `Always reply in French`. The file's contents come first even if you pass `--append-system-prompt` before `--append-system-prompt-file`. | ||||
| 164 | + | ||||
| 165 | +When the replacement text combines instructions that are the same on every run with context that changes per run, add a line containing only `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__` between the instructions and the context. Claude Code splits the prompt at the first such line and removes that line, so the part above it stays cached while the part below changes. Requires Claude Code v2.1.275 or later. [Cache the static part of a custom prompt](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt) lists the configurations where the split applies. | ||||
| 166 | + | ||||
| 167 | +Choose based on whether Claude Code's default identity still fits your task. Use an append flag when Claude should remain a coding assistant that also follows your extra rules: per-invocation instructions, output formatting, or domain context for a `-p` script. Appending preserves the default tool guidance, safety instructions, and coding conventions, so you only supply what differs. Use a replacement flag when the surface, identity, or permission model differs from Claude Code's, like a non-coding agent in a pipeline that no human watches. Replacing drops all of the default prompt, including tool guidance and safety instructions, so you take responsibility for whatever your task still needs. | ||||
| 168 | + | ||||
| 169 | +For persistent personas you can switch between and share across a project, use [output styles](https://code.claude.com/docs/en/output-styles.md). For project conventions Claude should always follow, use [CLAUDE.md](https://code.claude.com/docs/en/memory.md). The [Agent SDK guide on system prompts](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#decide-on-a-starting-point) covers the same decision in more depth. | ||||
| 170 | + | ||||
| 171 | +#### System prompt flags in resumed conversations | ||||
| 172 | + | ||||
| 173 | +By default, Claude Code builds the system prompt once, on a conversation's first request, with the text from any system prompt flags applied, and records it in the session. Until the conversation is compacted, every later request uses that recorded prompt, including after you return to the conversation with `--resume` or `--continue`. If you pass different system prompt flag text, or none, on that later launch, it takes effect once the conversation is compacted or when you start a new conversation. | ||||
| 174 | + | ||||
| 175 | +Outside of [cloud sessions](https://code.claude.com/docs/en/cloud-environments.md), if you start Claude Code in [bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode) by passing `--bare` or setting `CLAUDE_CODE_SIMPLE=1`, recording stays off unless you pass `--system-prompt-snapshot on`. Before v2.1.268, sessions that don't [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), including sessions on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, rebuilt the prompt on every request and `--system-prompt-snapshot` had no effect. | ||||
| 176 | + | ||||
| 177 | +To rebuild the prompt on every request instead, for example while you iterate on its wording across `--continue` runs, pass `--system-prompt-snapshot off`. Before v2.1.265, passing any of the system prompt flags also turned recording off unless you passed `--system-prompt-snapshot on`. | ||||
| 178 | + | ||||
| 179 | +## See also | ||||
| 180 | + | ||||
| 181 | +* [Chrome extension](https://code.claude.com/docs/en/chrome.md) - Browser automation and web testing | ||||
| 182 | +* [Interactive mode](https://code.claude.com/docs/en/interactive-mode.md) - Shortcuts, input modes, and interactive features | ||||
| 183 | +* [Quickstart guide](https://code.claude.com/docs/en/quickstart.md) - Getting started with Claude Code | ||||
| 184 | +* [Common workflows](https://code.claude.com/docs/en/common-workflows.md) - Advanced workflows and patterns | ||||
| 185 | +* [Settings](https://code.claude.com/docs/en/settings.md) - Configuration options | ||||
| 186 | +* [Agent SDK documentation](https://code.claude.com/docs/en/agent-sdk/overview.md) - Programmatic usage and integrations | ||||
added
docs/claude-code-docs/headless.md
+416 −0
@@ -0,0 +1,416 @@ | |||||
| 1 | +> ## Documentation Index | ||||
| 2 | +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt | ||||
| 3 | +> Use this file to discover all available pages before exploring further. | ||||
| 4 | + | ||||
| 5 | +# Run Claude Code programmatically | ||||
| 6 | + | ||||
| 7 | +> Use the Agent SDK to run Claude Code programmatically from the CLI, Python, or TypeScript. | ||||
| 8 | + | ||||
| 9 | +The [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as [Python](https://code.claude.com/docs/en/agent-sdk/python.md) and [TypeScript](https://code.claude.com/docs/en/agent-sdk/typescript.md) packages for full programmatic control. | ||||
| 10 | + | ||||
| 11 | +To run Claude Code in non-interactive mode, pass `-p` with your prompt and the [CLI options](https://code.claude.com/docs/en/cli-reference.md) you need: | ||||
| 12 | + | ||||
| 13 | +```bash theme={null} | ||||
| 14 | +claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash" | ||||
| 15 | +``` | ||||
| 16 | + | ||||
| 17 | +This page covers using the Agent SDK via the CLI (`claude -p`). For the Python and TypeScript SDK packages with structured outputs, tool approval callbacks, and native message objects, see the [full Agent SDK documentation](https://code.claude.com/docs/en/agent-sdk/overview.md). | ||||
| 18 | + | ||||
| 19 | +## Basic usage | ||||
| 20 | + | ||||
| 21 | +Add the `-p` (or `--print`) flag to any `claude` command to run it non-interactively. Not every [CLI option](https://code.claude.com/docs/en/cli-reference.md) combines with `-p`. Claude Code rejects `--bg`, and rejects `--cloud` with a task description, with an error naming the conflict; `--cloud` with a session ID and `-p` instead [queues a message into that cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-follow-ups-from-the-cli) and exits. Options you'll combine with `-p` often include: | ||||
| 22 | + | ||||
| 23 | +* `--continue` for [continuing conversations](#continue-conversations) | ||||
| 24 | +* `--allowedTools` for [auto-approving tools](#auto-approve-tools) | ||||
| 25 | +* `--output-format` for [structured output](#get-structured-output) | ||||
| 26 | + | ||||
| 27 | +This example asks Claude a question about your codebase and prints the response: | ||||
| 28 | + | ||||
| 29 | +```bash theme={null} | ||||
| 30 | +claude -p "What does the auth module do?" | ||||
| 31 | +``` | ||||
| 32 | + | ||||
| 33 | +Claude Code exits with code 0 on success and a non-zero code when the run fails, so your scripts can branch on the exit status. If you pass an invalid flag, Claude Code reports the error to stderr before the run starts. When a failure happens inside the run, such as missing authentication, Claude Code prints the failure as the result on stdout. | ||||
| 34 | + | ||||
| 35 | +### Start faster with bare mode | ||||
| 36 | + | ||||
| 37 | +Add `--bare` to reduce startup time by skipping auto-discovery of hooks, skills, custom commands, [subagents](https://code.claude.com/docs/en/sub-agents.md), installed plugins, MCP servers, auto memory, and CLAUDE.md. Without it, `claude -p` discovers and loads them as an interactive session would, including anything configured in the working directory or `~/.claude`. | ||||
| 38 | + | ||||
| 39 | +Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's `~/.claude` or an MCP server in the project's `.mcp.json` won't run, because bare mode never reads them. A directory you name with `--add-dir` is a partial exception: bare mode loads skills from its `.claude/skills/` folder, but still skips its `.claude/commands/` and `.claude/agents/` folders. [Skills from additional directories](https://code.claude.com/docs/en/skills.md#skills-from-additional-directories) covers what does and doesn't load. | ||||
| 40 | + | ||||
| 41 | +Without `--bare`, a `-p` session runs the hooks in a project's `.claude/settings.json` and connects the servers in its `.mcp.json`, even in a folder you've never trusted. A `-p` session shows no workspace trust dialog and no per-server approval prompt. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) covers each kind of repository content under `-p` and how to keep it out. | ||||
| 42 | + | ||||
| 43 | +This example runs a one-off summarize task in bare mode and pre-approves the Read tool so the call completes without a permission prompt. Set `ANTHROPIC_API_KEY` before running it, because bare mode doesn't use your subscription login: | ||||
| 44 | + | ||||
| 45 | +```bash theme={null} | ||||
| 46 | +claude --bare -p "Summarize README.md" --allowedTools "Read" | ||||
| 47 | +``` | ||||
| 48 | + | ||||
| 49 | +In bare mode, Claude Code never reads OAuth credentials or the system keychain. For the Anthropic API, set `ANTHROPIC_API_KEY` in the environment, with a key created in the [Claude Console](https://platform.claude.com), or supply an `apiKeyHelper` in the `--settings` JSON. Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry continue to read their own provider credentials as usual. | ||||
| 50 | + | ||||
| 51 | +In bare mode Claude has access to the Bash, file read, and file edit tools. Pass any context you need with a flag: | ||||
| 52 | + | ||||
| 53 | +| To load | Use | | ||||
| 54 | +| - | - | | ||||
| 55 | +| System prompt additions | `--append-system-prompt`, `--append-system-prompt-file` | | ||||
| 56 | +| Settings | `--settings <file-or-json>` | | ||||
| 57 | +| MCP servers | `--mcp-config <file-or-json>` | | ||||
| 58 | +| [Custom agents](https://code.claude.com/docs/en/sub-agents.md#choose-the-subagent-scope) | `--agents <file-or-json>` | | ||||
| 59 | +| A plugin | `--plugin-dir <path>`, `--plugin-url <url>` | | ||||
| 60 | + | ||||
| 61 | +Bare mode also limits what happens while the session runs: | ||||
| 62 | + | ||||
| 63 | +* **MCP servers**: only servers supplied on the command line connect, for example with `--mcp-config`. In an interactive session, Claude Code also skips the automatic IDE connection unless you pass `--ide`. | ||||
| 64 | +* **System reminders**: Claude gets your prompts and the tool results without the [system reminders](https://code.claude.com/docs/en/glossary.md#system-reminder) Claude Code would add alongside them. For example, Claude isn't told when a file it read earlier changes on disk, and it doesn't get the list of available skills, including skills from an `--add-dir` folder. | ||||
| 65 | +* **Background tasks**: Claude can't run background commands or background subagents, and the other features that [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/en/env-vars) turns off are off too. A command that reaches its [timeout](https://code.claude.com/docs/en/tools-reference.md#timeout-and-output-limits) stops instead of [moving to the background](https://code.claude.com/docs/en/tools-reference.md#background-commands). | ||||
| 66 | + | ||||
| 67 | +Before v2.1.286, these limits held only partly: an interactive `--bare` session connected the MCP servers that a normal session would, every `--bare` session sent system reminders, and background tasks stayed available. | ||||
| 68 | + | ||||
| 69 | +> [!NOTE] | ||||
| 70 | +> | ||||
| 71 | +> `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release. | ||||
| 72 | + | ||||
| 73 | +### Background tasks at exit | ||||
| 74 | + | ||||
| 75 | +After Claude finishes its turn and stdin has closed, a `claude -p` run can stay open to wait for background work that Claude started. | ||||
| 76 | + | ||||
| 77 | +Unless a background command that the main conversation started is still running, Claude Code stops whatever is still running after 10 minutes of continuous idle waiting by default and drops its partial result. To change the 10-minute cap, set [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](https://code.claude.com/docs/en/env-vars), or set it to `0` to wait without one. | ||||
| 78 | + | ||||
| 79 | +The run waits for background work such as background commands, subagents and workflows, Monitor watches, and pending `/loop` wakeups: | ||||
| 80 | + | ||||
| 81 | +* **[Background commands](https://code.claude.com/docs/en/tools-reference.md#background-commands)**: for a command that the main conversation started, for example a dev server or a watch build, the run waits until the command exits or reaches its [time limit](https://code.claude.com/docs/en/tools-reference.md#time-limit-for-background-commands). Claude then takes one more turn with the outcome. While the command runs, the 10-minute cap doesn't end the wait. | ||||
| 82 | +* **Background [subagents](https://code.claude.com/docs/en/sub-agents.md) and workflows**: the run stays open until that work completes, because its result is part of the final output. | ||||
| 83 | +* **[Monitor](https://code.claude.com/docs/en/tools-reference.md#monitor-tool) watches**: the run waits until the watch times out or the 10-minute cap ends the wait, whichever comes first. While it waits, Claude keeps responding to what the watch reports. By default, a watch times out five minutes after Claude starts it. | ||||
| 84 | +* **Pending wakeups**: in a run whose prompt you passed as text rather than with `--input-format stream-json`, when Claude has scheduled a [self-paced `/loop` wakeup](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval), the run waits for each wakeup to fire and runs its iteration until the [loop ends](https://code.claude.com/docs/en/scheduled-tasks.md#stop-a-loop), even past the 10-minute cap. | ||||
| 85 | + | ||||
| 86 | +When stderr is a terminal and the run has waited five seconds, Claude Code prints a line to stderr that starts with `Waiting for background work to finish` and names the work. With [`json` or `stream-json` output](#get-structured-output), the line prints only when stdout isn't a terminal, so the JSON your script reads never carries it. | ||||
| 87 | + | ||||
| 88 | +If the run reaches its [`--max-budget-usd`](https://code.claude.com/docs/en/cli-reference#cli-flags) cap, Claude Code stops the remaining background work instead of waiting. | ||||
| 89 | + | ||||
| 90 | +When background work starts another turn, the run prints each turn's result with the default `text` output and the last turn's result with `json` output. Before v2.1.295, the run printed only the last turn's result with `text` output too. | ||||
| 91 | + | ||||
| 92 | +#### MCP work when a non-interactive run ends | ||||
| 93 | + | ||||
| 94 | +A `claude -p` run doesn't wait for MCP work in the background: | ||||
| 95 | + | ||||
| 96 | +* **[MCP tasks](https://code.claude.com/docs/en/mcp.md#mcp-tasks-that-run-on-the-server)**: on a remote server the job goes on. To follow it again, [resume that session](https://code.claude.com/docs/en/mcp.md#exit-clear-or-resume-while-an-mcp-task-runs), not as a one-shot `claude -p "<prompt>"` run. | ||||
| 97 | +* **MCP calls that [automatic backgrounding](https://code.claude.com/docs/en/mcp.md#automatic-backgrounding-of-long-tool-calls) moved**: the call's result is lost. | ||||
| 98 | + | ||||
| 99 | +### Stop a run with SIGTERM | ||||
| 100 | + | ||||
| 101 | +If you stop a `claude -p` run with SIGTERM, for example with `kill` or from a process supervisor, Claude Code exits with code 143. Claude Code leaves the turn that was in progress unfinished and records no result for it. To end the turn instead, send SIGINT, or call the Agent SDK's `interrupt()`, before you stop the process. | ||||
| 102 | + | ||||
| 103 | +On SIGTERM, Claude Code terminates the process tree of any Bash command that is still running. Claude Code then runs [`SessionEnd` hooks](https://code.claude.com/docs/en/hooks#sessionend) and exits. While exiting, Claude Code starts no new tool call, sends no new model request, and runs no hook other than `SessionEnd`. If the run was in the middle of a command or waiting on a permission prompt when the signal arrived, Claude Code handles that step as follows: | ||||
| 104 | + | ||||
| 105 | +* **Running a command**: Claude Code records the command as killed in the session. | ||||
| 106 | +* **Waiting for an answer to a permission prompt**: if you send SIGTERM to the process, Claude Code leaves the prompt unanswered. If your program closes the session through the Agent SDK, the SDK ends Claude Code's input before sending any signal, and Claude Code cancels the prompt as soon as the input ends. | ||||
| 107 | + | ||||
| 108 | +When you [resume the session](#continue-conversations), Claude Code leaves the interrupted turn as it is, and your next prompt drives the conversation. To have Claude Code continue the interrupted turn on resume instead, set [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](https://code.claude.com/docs/en/env-vars). | ||||
| 109 | + | ||||
| 110 | +### If the working directory is deleted | ||||
| 111 | + | ||||
| 112 | +If the working directory of a `claude -p` or Agent SDK session is deleted mid-session, the session keeps running. When a turn starts while the directory is missing, Claude Code emits a [warning message](https://code.claude.com/docs/en/agent-sdk/typescript.md#sdkinformationalmessage) in `stream-json` output, and shell commands fail until the directory exists again. | ||||
| 113 | + | ||||
| 114 | +## Examples | ||||
| 115 | + | ||||
| 116 | +These examples highlight common CLI patterns. Where a command names a file such as `auth.py` or `build-error.txt`, substitute a file from your own project. In CI or other scripted environments, add [`--bare`](#start-faster-with-bare-mode) so Claude Code starts without loading the host's hooks, plugins, auto memory, or `CLAUDE.md`. | ||||
| 117 | + | ||||
| 118 | +### Pipe data through Claude | ||||
| 119 | + | ||||
| 120 | +Non-interactive mode reads stdin, so you can pipe data in and redirect the response out like any other command-line tool. | ||||
| 121 | + | ||||
| 122 | +This example pipes a build log into Claude and writes the explanation to a file: | ||||
| 123 | + | ||||
| 124 | +```bash theme={null} | ||||
| 125 | +cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt | ||||
| 126 | +``` | ||||
| 127 | + | ||||
| 128 | +With `--output-format json`, the response payload includes `total_cost_usd` and a per-model cost breakdown, so scripted callers can track spend without consulting the [usage dashboard](https://code.claude.com/docs/en/costs.md). When you continue an earlier conversation with `--continue` or `--resume`, the run reports the conversation's whole total, [earlier runs' spend included](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md#accumulate-costs-across-multiple-calls). Both figures are [client-side estimates](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md) and can differ from your actual bill. | ||||
| 129 | + | ||||
| 130 | +> [!NOTE] | ||||
| 131 | +> | ||||
| 132 | +> Piped stdin is capped at 10MB. If you exceed the cap, Claude Code exits with a clear error and a non-zero status. To work with larger inputs, write the content to a file and reference the file path in your prompt instead of piping it. | ||||
| 133 | + | ||||
| 134 | +If Claude Code can't read stdin, for example because the process that started it disconnected its end, Claude Code prints a warning to stderr and continues with the prompt from the command line. | ||||
| 135 | + | ||||
| 136 | +### Add Claude to a build script | ||||
| 137 | + | ||||
| 138 | +You can wrap a non-interactive call in a script to use Claude as a project-specific linter or reviewer. | ||||
| 139 | + | ||||
| 140 | +This `package.json` script pipes the diff against `main` into Claude and asks it to report typos. Piping the diff means Claude doesn't need Bash permission to read it, and the escaped double quotes keep the script portable to Windows: | ||||
| 141 | + | ||||
| 142 | +```json theme={null} | ||||
| 143 | +{ | ||||
| 144 | + "scripts": { | ||||
| 145 | + "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\"" | ||||
| 146 | + } | ||||
| 147 | +} | ||||
| 148 | +``` | ||||
| 149 | + | ||||
| 150 | +Run it with `npm run lint:claude`. | ||||
| 151 | + | ||||
| 152 | +### Get structured output | ||||
| 153 | + | ||||
| 154 | +Use `--output-format` to control how responses are returned: | ||||
| 155 | + | ||||
| 156 | +* `text` (default): plain text output | ||||
| 157 | +* `json`: structured JSON with result, session ID, and metadata | ||||
| 158 | +* `stream-json`: newline-delimited JSON for real-time streaming | ||||
| 159 | + | ||||
| 160 | +This example returns a project summary as JSON with session metadata, with the text result in the `result` field: | ||||
| 161 | + | ||||
| 162 | +```bash theme={null} | ||||
| 163 | +claude -p "Summarize this project" --output-format json | ||||
| 164 | +``` | ||||
| 165 | + | ||||
| 166 | +To get output conforming to a specific schema, use `--output-format json` with `--json-schema` and a [JSON Schema](https://json-schema.org/) definition. The response includes metadata about the request (session ID, usage, etc.) with the structured output in the `structured_output` field. | ||||
| 167 | + | ||||
| 168 | +This example extracts function names and returns them as an array of strings: | ||||
| 169 | + | ||||
| 170 | +```bash theme={null} | ||||
| 171 | +claude -p "Extract the main function names from auth.py" \ | ||||
| 172 | + --output-format json \ | ||||
| 173 | + --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' | ||||
| 174 | +``` | ||||
| 175 | + | ||||
| 176 | +If the value isn't a valid JSON Schema, `claude` exits with `Error: --json-schema is not a valid JSON Schema` followed by the validator's diagnostic. Claude Code accepts schemas that use the `format` keyword, such as `"format": "email"`, but treats `format` as an annotation and doesn't enforce it. | ||||
| 177 | + | ||||
| 178 | +If a run ends without valid structured output, for example because Claude declined the request, the response has no `structured_output` field. Before your script uses `structured_output`, check that the field is present. | ||||
| 179 | + | ||||
| 180 | +> [!TIP] | ||||
| 181 | +> | ||||
| 182 | +> Use a tool like [jq](https://jqlang.org/) to parse the response and extract specific fields: | ||||
| 183 | +> | ||||
| 184 | +> ```bash theme={null} | ||||
| 185 | +> # Extract the text result | ||||
| 186 | +> claude -p "Summarize this project" --output-format json | jq -r '.result' | ||||
| 187 | +> | ||||
| 188 | +> # Extract structured output | ||||
| 189 | +> claude -p "Extract function names from auth.py" \ | ||||
| 190 | +> --output-format json \ | ||||
| 191 | +> --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \ | ||||
| 192 | +> | jq '.structured_output' | ||||
| 193 | +> ``` | ||||
| 194 | + | ||||
| 195 | +### Stream responses | ||||
| 196 | + | ||||
| 197 | +Use `--output-format stream-json` with `--verbose` and `--include-partial-messages` to receive tokens as they're generated. Each line is a JSON object representing an event: | ||||
| 198 | + | ||||
| 199 | +```bash theme={null} | ||||
| 200 | +claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages | ||||
| 201 | +``` | ||||
| 202 | + | ||||
| 203 | +The last line of the stream is a `result` message with the final response text, cost, and session metadata. | ||||
| 204 | + | ||||
| 205 | +If your consumer reads the stream slowly, Claude Code waits for the queued output to drain before exiting, scaling the wait with how much is still queued, capped at 30 seconds. | ||||
| 206 | + | ||||
| 207 | +The following example uses [jq](https://jqlang.org/) to filter for text deltas and display only the streaming text. The `-r` flag outputs raw strings (no quotes) and `-j` joins without newlines so tokens stream continuously: | ||||
| 208 | + | ||||
| 209 | +```bash theme={null} | ||||
| 210 | +claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \ | ||||
| 211 | + jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text' | ||||
| 212 | +``` | ||||
| 213 | + | ||||
| 214 | +For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](https://code.claude.com/docs/en/agent-sdk/streaming-output.md) in the Agent SDK documentation. | ||||
| 215 | + | ||||
| 216 | +#### Follow subagent messages | ||||
| 217 | + | ||||
| 218 | +Messages from [subagents](https://code.claude.com/docs/en/sub-agents.md) and from skills that [run in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) appear in the stream as `assistant` and `user` messages. Their `parent_tool_use_id` field says which run each one belongs to. Messages from the main conversation carry `null` in that field. | ||||
| 219 | + | ||||
| 220 | +The first message from a forked skill, or from a subagent running in the [foreground](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background), is a `user` message carrying the prompt or skill content that drives it. After that first message, Claude Code emits: | ||||
| 221 | + | ||||
| 222 | +* **By default**: the run's `tool_use` and `tool_result` blocks. | ||||
| 223 | +* **With [`--forward-subagent-text`](https://code.claude.com/docs/en/cli-reference#cli-flags) or [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](https://code.claude.com/docs/en/env-vars)**: the run's text and thinking blocks too, so you can reconstruct each run's transcript. | ||||
| 224 | + | ||||
| 225 | +When you enable either option, Claude Code forwards messages from [subagents at every nesting depth](https://code.claude.com/docs/en/sub-agents.md#let-subagents-spawn-their-own-subagents), whether each one was spawned with the Agent tool or started as a forked skill. In `parent_tool_use_id`, the nested subagent's messages carry the ID of the Agent or Skill tool call that started it, so you can rebuild the full nesting tree by following those IDs. | ||||
| 226 | + | ||||
| 227 | +A run that Claude starts with a tool call carries that tool call's ID. A forked skill that you start by passing `/<skill-name>` as the prompt has no tool call, so its messages carry a `forked-command-` value instead and arrive after it finishes. Find how the run started in the first column: | ||||
| 228 | + | ||||
| 229 | +| How the run starts | `parent_tool_use_id` | When its messages arrive | | ||||
| 230 | +| :- | :- | :- | | ||||
| 231 | +| Claude calls the Agent tool from the main conversation | The ID of that Agent `tool_use` block | While the subagent works | | ||||
| 232 | +| Claude calls the Skill tool for a forked skill from the main conversation | The ID of that Skill `tool_use` block | While the forked skill works | | ||||
| 233 | +| You pass `/<skill-name>` as the prompt | A value that starts with `forked-command-` | Together and in order after the forked skill finishes | | ||||
| 234 | + | ||||
| 235 | +For a forked skill started from the prompt, match `parent_tool_use_id` on the `forked-command-` prefix, because the name after it can differ from the one you typed. | ||||
| 236 | + | ||||
| 237 | +If some of these messages are missing from your stream, check your Claude Code version against these minimums: | ||||
| 238 | + | ||||
| 239 | +* **A forked skill that Claude starts with the Skill tool from the main conversation**: v2.1.86 or later for its `tool_use` and `tool_result` blocks, and v2.1.265 or later for its first `user` message and its text and thinking blocks | ||||
| 240 | +* **Messages of subagents that a forked skill spawns, and of forked skills started inside a subagent or another forked skill**: v2.1.275 or later | ||||
| 241 | +* **Messages of a forked skill you start by passing `/<skill-name>` as the prompt**: v2.1.287 or later | ||||
| 242 | + | ||||
| 243 | +#### Handle API retries | ||||
| 244 | + | ||||
| 245 | +When an API request fails with a retryable error, Claude Code emits a `system/api_retry` event before retrying. On v2.1.246 or later, when a `401` or `403` rejects an [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper) credential, Claude Code makes the first two retries quietly with no event, then emits the event as usual from the third consecutive retry onward. The quiet retries still count toward `attempt`. You can use the event to show retry progress in your own interface. | ||||
| 246 | + | ||||
| 247 | +| Field | Type | Description | | ||||
| 248 | +| - | - | - | | ||||
| 249 | +| `type` | `"system"` | message type | | ||||
| 250 | +| `subtype` | `"api_retry"` | identifies this as a retry event | | ||||
| 251 | +| `attempt` | integer | current attempt number, starting at 1 | | ||||
| 252 | +| `max_retries` | integer | total retries permitted for this failure's cause | | ||||
| 253 | +| `retry_delay_ms` | integer | milliseconds until the next attempt | | ||||
| 254 | +| `error_status` | integer or null | HTTP status code of the failed attempt, or `null` when the attempt got no HTTP response from the API | | ||||
| 255 | +| `no_response` | object, optional | present only when the failed attempt got [no response headers in time](https://code.claude.com/docs/en/errors.md#no-response-from-api). `waited_ms` is how long that attempt waited and `retry_wait_ms` is how long the retry will wait. Requires Claude Code v2.1.261 or later | | ||||
| 256 | +| `error` | string | error category: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, or `unknown` | | ||||
| 257 | +| `uuid` | string | unique event identifier | | ||||
| 258 | +| `session_id` | string | session the event belongs to | | ||||
| 259 | + | ||||
| 260 | +#### Read session metadata | ||||
| 261 | + | ||||
| 262 | +The `system/init` event reports session metadata including the model, tools, MCP servers, and loaded plugins. It is the first event in the stream unless startup events precede it: | ||||
| 263 | + | ||||
| 264 | +* `plugin_install` events, when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](https://code.claude.com/docs/en/env-vars) is set. | ||||
| 265 | +* [`hook_started`, `hook_progress`, and `hook_response` events](https://code.claude.com/docs/en/agent-sdk/typescript#sdkhookstartedmessage), while a configured [`SessionStart`](https://code.claude.com/docs/en/hooks#sessionstart) or [`Setup`](https://code.claude.com/docs/en/hooks#setup) hook runs. These stream as the hook produces them. | ||||
| 266 | + | ||||
| 267 | +The event also carries an optional `capabilities` array of strings naming the protocol behaviors this Claude Code version implements, such as `interrupt_receipt_v1` or `interrupt_cancel_queued_v1`. Check it to feature-detect instead of comparing version strings, and ignore values you don't recognize. See [`SDKSystemMessage`](https://code.claude.com/docs/en/agent-sdk/typescript#sdksystemmessage) for the capability list. | ||||
| 268 | + | ||||
| 269 | +#### Fail CI when a plugin or MCP server doesn't load | ||||
| 270 | + | ||||
| 271 | +Use the plugin fields in the `system/init` event to catch a plugin that didn't load: | ||||
| 272 | + | ||||
| 273 | +| Field | Type | Description | | ||||
| 274 | +| - | - | - | | ||||
| 275 | +| `plugins` | array | plugins that loaded successfully, each with `name` and `path` | | ||||
| 276 | +| `plugin_errors` | array | plugin load-time errors, each with `plugin`, `type`, and `message`. Includes unsatisfied dependency versions and `--plugin-dir` load failures such as a missing path or invalid archive. A plugin that didn't load is absent from `plugins`. The key is omitted when there are no errors | | ||||
| 277 | + | ||||
| 278 | +When a `--plugin-dir` directory or archive itself fails to load, its `plugin_errors` entry includes the resolved absolute path as `path`. Use it to tell which of several `--plugin-dir` values failed. The `path` field requires Claude Code v2.1.283 or later. | ||||
| 279 | + | ||||
| 280 | +Use the MCP server fields the same way. When you pass [`--mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags) with `-p`, Claude Code waits for still-pending servers before running the first turn, up to the [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) startup timeout, 30 seconds by default. A remote server with a [cached tool list](https://code.claude.com/docs/en/agent-sdk/mcp.md#connection-timing) skips the wait, shows `pending` in `system/init`, and connects on its first tool call. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#connection-timing), a shorter wait applies instead. The wait requires Claude Code v2.1.221 or later. | ||||
| 281 | + | ||||
| 282 | +Claude Code validates each `--mcp-config` entry at startup and skips entries that fail validation, for example a `url` entry with no `type`. The run continues and exits cleanly, so check these fields to catch a server that never loaded: | ||||
| 283 | + | ||||
| 284 | +| Field | Type | Description | | ||||
| 285 | +| - | - | - | | ||||
| 286 | +| `mcp_servers` | array | MCP servers in the session, each with `name` and `status` | | ||||
| 287 | +| `mcp_server_errors` | array | `--mcp-config` entries skipped by config validation, each with `name`, `type`, and `message`. `type` is a skip category such as `unknown_type`, `url_missing_type`, `invalid_config`, or `reserved_name`; treat values you don't recognize as a generic skip. Affected servers are absent from `mcp_servers`. The key is omitted when there are no errors, so a CI gate can fail on a non-empty array | | ||||
| 288 | + | ||||
| 289 | +When you run the command yourself in a terminal, Claude Code also prints a startup warning to stderr, such as `Warning: 1 MCP server skipped due to invalid config:`, followed by the reason for each skipped entry. | ||||
| 290 | + | ||||
| 291 | +When you redirect stderr, or when a program such as a CI runner or an SDK host captures it, Claude Code prints no warning. It reports the skipped entries only in the `mcp_server_errors` field. | ||||
| 292 | + | ||||
| 293 | +#### Track plugin installs | ||||
| 294 | + | ||||
| 295 | +When [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](https://code.claude.com/docs/en/env-vars) is set, Claude Code emits `system/plugin_install` events while marketplace plugins install before the first turn. Use these to surface install progress in your own UI. | ||||
| 296 | + | ||||
| 297 | +| Field | Type | Description | | ||||
| 298 | +| - | - | - | | ||||
| 299 | +| `type` | `"system"` | message type | | ||||
| 300 | +| `subtype` | `"plugin_install"` | identifies this as a plugin install event | | ||||
| 301 | +| `status` | `"started"`, `"installed"`, `"failed"`, or `"completed"` | `started` and `completed` bracket the overall install; `installed` and `failed` report individual marketplaces | | ||||
| 302 | +| `name` | string, optional | marketplace name, present on `installed` and `failed` | | ||||
| 303 | +| `error` | string, optional | failure message, present on `failed` | | ||||
| 304 | +| `uuid` | string | unique event identifier | | ||||
| 305 | +| `session_id` | string | session the event belongs to | | ||||
| 306 | + | ||||
| 307 | +### Auto-approve tools | ||||
| 308 | + | ||||
| 309 | +Use `--allowedTools` to let Claude use certain tools without prompting. Listing `Read` and `Edit` lets Claude read and edit files without asking for permission, apart from reads from [network paths](https://code.claude.com/docs/en/permissions.md#network-paths). Listing `Bash` does the same for shell commands, except in a run that starts in [auto mode](https://code.claude.com/docs/en/permission-modes.md#how-auto-mode-evaluates-actions), where Claude Code drops a bare `Bash` entry as a broad allow rule and auto mode evaluates each command instead. This example runs a test suite and fixes failures with those three tools listed: | ||||
| 310 | + | ||||
| 311 | +```bash theme={null} | ||||
| 312 | +claude -p "Run the test suite and fix any failures" \ | ||||
| 313 | + --allowedTools "Bash,Read,Edit" | ||||
| 314 | +``` | ||||
| 315 | + | ||||
| 316 | +Calls to tools you didn't list run if they need no approval. In a [Manual mode](https://code.claude.com/docs/en/permission-modes.md#available-modes) `claude -p` run, a call that needs approval is denied unless something approves it, such as a [`PermissionRequest` hook](https://code.claude.com/docs/en/hooks#permissionrequest) or a [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags). With Claude Code v2.1.302 or later, `claude -p` runs start in Manual mode when [nothing sets a permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-non-interactive-run-starts-in). | ||||
| 317 | + | ||||
| 318 | +To set a baseline for the whole session instead of listing individual tools, pass a [permission mode](https://code.claude.com/docs/en/permission-modes.md) with `--permission-mode`, such as `auto`, `dontAsk`, or `acceptEdits`: | ||||
| 319 | + | ||||
| 320 | +* **`auto`**: pass `--permission-mode auto` to have a classifier review most actions instead of you | ||||
| 321 | +* **`dontAsk`**: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs, though a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you installed can still approve some of those calls. To check which calls a mod can approve, see [Extend permissions with hooks](https://code.claude.com/docs/en/permissions.md#precedence-among-rules-hooks-and-mods). | ||||
| 322 | + | ||||
| 323 | + Actions that need no approval in Manual mode still run, such as file reads in your working directories and the [read-only command set](https://code.claude.com/docs/en/permissions.md#read-only-commands). Actions covered by your `--allowedTools` entries or `permissions.allow` rules also run. `AskUserQuestion`, connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools), MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool), and [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths) are denied even when an allow rule matches | ||||
| 324 | +* **`acceptEdits`**: Claude writes files without prompting, and Claude Code auto-approves common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp`. The [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) still apply. Apart from the read-only command set, other shell commands and network requests still need an `--allowedTools` entry or a `permissions.allow` rule. See [what `acceptEdits` auto-approves](https://code.claude.com/docs/en/permission-modes#auto-approve-file-edits-with-acceptedits-mode) for the full list | ||||
| 325 | + | ||||
| 326 | +This example applies lint fixes with `acceptEdits` as the baseline: | ||||
| 327 | + | ||||
| 328 | +```bash theme={null} | ||||
| 329 | +claude -p "Apply the lint fixes" --permission-mode acceptEdits | ||||
| 330 | +``` | ||||
| 331 | + | ||||
| 332 | +### Turn off permission prompts in unattended runs | ||||
| 333 | + | ||||
| 334 | +Pass `--permission-prompts none` when nobody is available to answer permission prompts, for example in a scheduled job. The flag matters most when your run has a permission host: an Agent SDK app with a [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/user-input), or an MCP tool you pass with [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags). Without the flag, your run waits for that host to answer each permission request. | ||||
| 335 | + | ||||
| 336 | +With the flag, your run doesn't consult the host or wait on it. Anything that would prompt is denied unless a `PermissionRequest` hook allows it, Claude is told that nobody can approve the request and not to retry it, and the run continues. In a `-p` run with no host, these requests are denied either way, and the flag also tells Claude not to retry them. Permission rules, [`PermissionRequest` hooks](https://code.claude.com/docs/en/hooks#permissionrequest), and the permission mode you set still decide every call first; Claude Code denies only the requests that nothing else resolves. | ||||
| 337 | + | ||||
| 338 | +This example runs an unattended task in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode). The classifier reviews each action as usual, and Claude Code denies anything that would have fallen back to a prompt: | ||||
| 339 | + | ||||
| 340 | +```bash theme={null} | ||||
| 341 | +claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none | ||||
| 342 | +``` | ||||
| 343 | + | ||||
| 344 | +With `--permission-prompts none`, Claude Code removes the tools that need an answer from a person, such as [`AskUserQuestion`](https://code.claude.com/docs/en/tools-reference#askuserquestion-tool-behavior), so Claude can't call them. Any [MCP elicitation request](https://code.claude.com/docs/en/mcp.md#respond-to-mcp-elicitation-requests) that no [`Elicitation` hook](https://code.claude.com/docs/en/hooks#elicitation) answers is cancelled. | ||||
| 345 | + | ||||
| 346 | +With `--output-format stream-json`, denials appear as `permission_denied` system messages, and the final result message lists them in `permission_denials`. | ||||
| 347 | + | ||||
| 348 | +> [!NOTE] | ||||
| 349 | +> | ||||
| 350 | +> The `--permission-prompts` flag requires Claude Code v2.1.259 or later. Earlier versions reject it with an unknown-option error. | ||||
| 351 | + | ||||
| 352 | +### Create a commit | ||||
| 353 | + | ||||
| 354 | +This example reviews staged changes and creates a commit with an appropriate message: | ||||
| 355 | + | ||||
| 356 | +```bash theme={null} | ||||
| 357 | +claude -p "Look at my staged changes and create an appropriate commit" \ | ||||
| 358 | + --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)" | ||||
| 359 | +``` | ||||
| 360 | + | ||||
| 361 | +The `--allowedTools` flag uses [permission rule syntax](https://code.claude.com/docs/en/settings-reference.md#permission-rule-syntax). The trailing ` *` enables prefix matching, so `Bash(git diff *)` allows any command starting with `git diff`. The space before `*` is important: without it, `Bash(git diff*)` would also match `git diff-index`. | ||||
| 362 | + | ||||
| 363 | +> [!NOTE] | ||||
| 364 | +> | ||||
| 365 | +> Command support differs in `-p` mode: | ||||
| 366 | +> | ||||
| 367 | +> * User-invoked [skills](https://code.claude.com/docs/en/skills.md) and custom commands work. Include `/skill-name` in the prompt string and Claude Code expands it before running. | ||||
| 368 | +> * Built-in commands that only run in the terminal interface, such as `/login`, aren't available. | ||||
| 369 | +> * `/model`, `/effort`, `/fast`, `/color`, and `/rename` accept the value as an argument, for example `/model sonnet`, and `/mcp` with no argument prints a text summary of server status. These forms follow each command's [availability notes](https://code.claude.com/docs/en/commands.md#all-commands). | ||||
| 370 | +> * To change a setting, pass `key=value` to `/config`, for example `/config thinking=false`. | ||||
| 371 | +> * `/output-style <style>` switches [output styles](https://code.claude.com/docs/en/output-styles.md) and `/output-style` alone lists them. Requires Claude Code v2.1.269 or later. | ||||
| 372 | + | ||||
| 373 | +### Customize the system prompt | ||||
| 374 | + | ||||
| 375 | +Use `--append-system-prompt` to add instructions while keeping Claude Code's default behavior. This example pipes a PR diff to Claude and instructs it to review for security vulnerabilities. Save it as a shell script, for example `review.sh`: | ||||
| 376 | + | ||||
| 377 | +```bash theme={null} | ||||
| 378 | +gh pr diff "$1" | claude -p \ | ||||
| 379 | + --append-system-prompt "You are a security engineer. Review for vulnerabilities." \ | ||||
| 380 | + --output-format json | ||||
| 381 | +``` | ||||
| 382 | + | ||||
| 383 | +In the script, `"$1"` stands for the first argument you pass on the command line. Run `bash review.sh 123` and the shell replaces `"$1"` with `123`, so the script fetches the diff for PR 123. Claude Code prints the review as JSON, with the text in the `result` field. | ||||
| 384 | + | ||||
| 385 | +See [system prompt flags](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags) for more options including `--system-prompt` to fully replace the default prompt. If you replace it, the run also starts without the [git status snapshot](https://code.claude.com/docs/en/settings-reference.md#includegitinstructions). | ||||
| 386 | + | ||||
| 387 | +### Continue conversations | ||||
| 388 | + | ||||
| 389 | +Use `--continue` to continue the most recent conversation, or `--resume` with a session ID to continue a specific conversation. On Claude Code v2.1.257 or later, when you pass `--continue`, Claude Code opens a [background session](https://code.claude.com/docs/en/sessions.md#where-the-session-picker-looks) that has finished, but not one that is still running. This example runs a review, then sends follow-up prompts: | ||||
| 390 | + | ||||
| 391 | +```bash theme={null} | ||||
| 392 | +# First request | ||||
| 393 | +claude -p "Review this codebase for performance issues" | ||||
| 394 | + | ||||
| 395 | +# Continue the most recent conversation | ||||
| 396 | +claude -p "Now focus on the database queries" --continue | ||||
| 397 | +claude -p "Generate a summary of all issues found" --continue | ||||
| 398 | +``` | ||||
| 399 | + | ||||
| 400 | +If you're running multiple conversations, capture the session ID to resume a specific one: | ||||
| 401 | + | ||||
| 402 | +```bash theme={null} | ||||
| 403 | +session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id') | ||||
| 404 | +claude -p "Continue that review" --resume "$session_id" | ||||
| 405 | +``` | ||||
| 406 | + | ||||
| 407 | +You can run the two commands from different directories: Claude Code [finds the session by its ID](https://code.claude.com/docs/en/sessions.md#where-the-session-picker-looks) in any project on this machine. | ||||
| 408 | + | ||||
| 409 | +In place of the session ID, you can pass `--resume` the absolute path to a session's `.jsonl` [transcript file](https://code.claude.com/docs/en/sessions.md#where-transcripts-are-stored), and Claude Code continues the conversation stored in that file. | ||||
| 410 | + | ||||
| 411 | +## Next steps | ||||
| 412 | + | ||||
| 413 | +* [Agent SDK quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart.md): build your first agent with Python or TypeScript | ||||
| 414 | +* [CLI reference](https://code.claude.com/docs/en/cli-reference.md): all CLI flags and options | ||||
| 415 | +* [GitHub Actions](https://code.claude.com/docs/en/github-actions.md): use the Agent SDK in GitHub workflows | ||||
| 416 | +* [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md): use the Agent SDK in GitLab pipelines | ||||
added
docs/claude-code-docs/hooks.md
+4244 −0
@@ -0,0 +1,4244 @@ | |||||
| 1 | +> ## Documentation Index | ||||
| 2 | +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt | ||||
| 3 | +> Use this file to discover all available pages before exploring further. | ||||
| 4 | + | ||||
| 5 | +# Hooks reference | ||||
| 6 | + | ||||
| 7 | +> Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, HTTP hooks, prompt hooks, and MCP tool hooks. | ||||
| 8 | + | ||||
| 9 | +> [!TIP] | ||||
| 10 | +> | ||||
| 11 | +> For a quickstart guide with examples, see [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide.md). | ||||
| 12 | + | ||||
| 13 | +Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle. Claude Code fires the same hook events wherever it runs: sessions in the terminal, IDE extensions, the [Desktop app](https://code.claude.com/docs/en/desktop-quickstart.md), and [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md). Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks, HTTP hooks, and MCP tool hooks. | ||||
| 14 | + | ||||
| 15 | +A plugin can also register hooks as JavaScript functions that Claude Code calls in its own process, which can draw in the interface as well as act on events. A plugin that does is a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md), and those function hooks are covered in [React to events](https://code.claude.com/docs/en/plugins/mods/events.md) rather than here. The hooks on this page keep working alongside mods. | ||||
| 16 | + | ||||
| 17 | +## Hook lifecycle | ||||
| 18 | + | ||||
| 19 | +Claude Code runs hooks at specific points during a session. When an event fires and a matcher matches, Claude Code passes JSON context about the event to your hook handler. For command hooks, input arrives on stdin. For HTTP hooks, it arrives as the POST request body. Your handler can then inspect the input, take action, and optionally return a decision. | ||||
| 20 | + | ||||
| 21 | +Events fall into three cadences: | ||||
| 22 | + | ||||
| 23 | +* per session: `SessionStart` and `SessionEnd` | ||||
| 24 | +* per turn: `UserPromptSubmit`, `Stop`, and `StopFailure` | ||||
| 25 | +* on every tool call inside the agentic loop: `PreToolUse` and `PostToolUse`, except [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) calls, which skip both | ||||
| 26 | + | ||||
| 27 | + | ||||
| 28 | + | ||||
| 29 | +The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one. | ||||
| 30 | + | ||||
| 31 | +| Event | When it fires | | ||||
| 32 | +| :- | :- | | ||||
| 33 | +| `SessionStart` | When a session begins or resumes | | ||||
| 34 | +| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts | | ||||
| 35 | +| `UserPromptSubmit` | When a prompt is submitted, before Claude processes it. Also fires on [turns Claude Code starts on its own](https://code.claude.com/docs/en/hooks.md#userpromptsubmit) | | ||||
| 36 | +| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion | | ||||
| 37 | +| `PreToolUse` | Before a tool call executes. Can block it | | ||||
| 38 | +| `PermissionRequest` | When a tool call needs a permission decision | | ||||
| 39 | +| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict | | ||||
| 40 | +| `PostToolUse` | After a tool call succeeds | | ||||
| 41 | +| `PostToolUseFailure` | After a tool call fails | | ||||
| 42 | +| `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call | | ||||
| 43 | +| `Notification` | When Claude Code sends a notification | | ||||
| 44 | +| `MessageDisplay` | While assistant message text is displayed | | ||||
| 45 | +| `SubagentStart` | When a subagent is spawned | | ||||
| 46 | +| `SubagentStop` | When a subagent finishes | | ||||
| 47 | +| `TaskCreated` | When a task is being created via `TaskCreate` | | ||||
| 48 | +| `TaskCompleted` | When a task is being marked as completed | | ||||
| 49 | +| `Stop` | When Claude finishes responding | | ||||
| 50 | +| `StopFailure` | When the turn ends due to an API error | | ||||
| 51 | +| `TeammateIdle` | When an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate is about to go idle | | ||||
| 52 | +| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session | | ||||
| 53 | +| `ConfigChange` | When a configuration file changes during a session | | ||||
| 54 | +| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv | | ||||
| 55 | +| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request | | ||||
| 56 | +| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch | | ||||
| 57 | +| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior | | ||||
| 58 | +| `WorktreeRemove` | When a worktree that a `WorktreeCreate` hook created is being removed | | ||||
| 59 | +| `PreCompact` | Before context compaction | | ||||
| 60 | +| `PostCompact` | After context compaction completes | | ||||
| 61 | +| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch | | ||||
| 62 | +| `PostModelSwitch` | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session | | ||||
| 63 | +| `Elicitation` | When an MCP server requests user input during a tool call | | ||||
| 64 | +| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server | | ||||
| 65 | +| `SessionEnd` | When a session terminates | | ||||
| 66 | + | ||||
| 67 | +### How a hook resolves | ||||
| 68 | + | ||||
| 69 | +To see how the event, the matcher, and the handler fit together, consider this `PreToolUse` hook that blocks destructive shell commands. | ||||
| 70 | + | ||||
| 71 | +**macOS/Linux** | ||||
| 72 | + | ||||
| 73 | +The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match: | ||||
| 74 | + | ||||
| 75 | +```json theme={null} | ||||
| 76 | +{ | ||||
| 77 | + "hooks": { | ||||
| 78 | + "PreToolUse": [ | ||||
| 79 | + { | ||||
| 80 | + "matcher": "Bash", | ||||
| 81 | + "hooks": [ | ||||
| 82 | + { | ||||
| 83 | + "type": "command", | ||||
| 84 | + "if": "Bash(rm *)", | ||||
| 85 | + "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh", | ||||
| 86 | + "args": [] | ||||
| 87 | + } | ||||
| 88 | + ] | ||||
| 89 | + } | ||||
| 90 | + ] | ||||
| 91 | + } | ||||
| 92 | +} | ||||
| 93 | +``` | ||||
| 94 | + | ||||
| 95 | +The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf`. Save it to `.claude/hooks/block-rm.sh` in your project and make it executable with `chmod +x .claude/hooks/block-rm.sh` so Claude Code can run it: | ||||
| 96 | + | ||||
| 97 | +```bash theme={null} | ||||
| 98 | +#!/bin/bash | ||||
| 99 | +# .claude/hooks/block-rm.sh | ||||
| 100 | +COMMAND=$(jq -r '.tool_input.command') | ||||
| 101 | + | ||||
| 102 | +if echo "$COMMAND" | grep -q 'rm -rf'; then | ||||
| 103 | + jq -n '{ | ||||
| 104 | + hookSpecificOutput: { | ||||
| 105 | + hookEventName: "PreToolUse", | ||||
| 106 | + permissionDecision: "deny", | ||||
| 107 | + permissionDecisionReason: "Destructive command blocked by hook" | ||||
| 108 | + } | ||||
| 109 | + }' | ||||
| 110 | +else | ||||
| 111 | + exit 0 # no decision; normal permission flow applies | ||||
| 112 | +fi | ||||
| 113 | +``` | ||||
| 114 | + | ||||
| 115 | +This script, like the other Bash examples on this page that parse JSON input, uses `jq`, so install `jq` and make sure it is on your `PATH` before trying them. | ||||
| 116 | + | ||||
| 117 | +**Windows (PowerShell)** | ||||
| 118 | + | ||||
| 119 | +The matcher `Bash|PowerShell` covers the [PowerShell tool](#powershell) as well as Bash. A single `if` rule matches only one tool's calls, so each tool gets its own handler: the first narrows to Bash subcommands matching `rm *`, the second to PowerShell commands matching `Remove-Item *`. Both run the same script through `powershell.exe`: | ||||
| 120 | + | ||||
| 121 | +```json theme={null} | ||||
| 122 | +{ | ||||
| 123 | + "hooks": { | ||||
| 124 | + "PreToolUse": [ | ||||
| 125 | + { | ||||
| 126 | + "matcher": "Bash|PowerShell", | ||||
| 127 | + "hooks": [ | ||||
| 128 | + { | ||||
| 129 | + "type": "command", | ||||
| 130 | + "if": "Bash(rm *)", | ||||
| 131 | + "command": "powershell.exe", | ||||
| 132 | + "args": [ | ||||
| 133 | + "-NoProfile", | ||||
| 134 | + "-ExecutionPolicy", | ||||
| 135 | + "Bypass", | ||||
| 136 | + "-File", | ||||
| 137 | + "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1" | ||||
| 138 | + ] | ||||
| 139 | + }, | ||||
| 140 | + { | ||||
| 141 | + "type": "command", | ||||
| 142 | + "if": "PowerShell(Remove-Item *)", | ||||
| 143 | + "command": "powershell.exe", | ||||
| 144 | + "args": [ | ||||
| 145 | + "-NoProfile", | ||||
| 146 | + "-ExecutionPolicy", | ||||
| 147 | + "Bypass", | ||||
| 148 | + "-File", | ||||
| 149 | + "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1" | ||||
| 150 | + ] | ||||
| 151 | + } | ||||
| 152 | + ] | ||||
| 153 | + } | ||||
| 154 | + ] | ||||
| 155 | + } | ||||
| 156 | +} | ||||
| 157 | +``` | ||||
| 158 | + | ||||
| 159 | +The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file. | ||||
| 160 | + | ||||
| 161 | +The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf` or `Remove-Item` followed by `-Recurse`. Save it to `.claude/hooks/block-rm.ps1` in your project: | ||||
| 162 | + | ||||
| 163 | +```powershell theme={null} | ||||
| 164 | +# .claude/hooks/block-rm.ps1 | ||||
| 165 | +$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json | ||||
| 166 | +$command = $callInput.tool_input.command | ||||
| 167 | + | ||||
| 168 | +if ($command -match 'rm -rf|Remove-Item.*-Recurse') { | ||||
| 169 | + @{ | ||||
| 170 | + hookSpecificOutput = @{ | ||||
| 171 | + hookEventName = "PreToolUse" | ||||
| 172 | + permissionDecision = "deny" | ||||
| 173 | + permissionDecisionReason = "Destructive command blocked by hook" | ||||
| 174 | + } | ||||
| 175 | + } | ConvertTo-Json | ||||
| 176 | +} else { | ||||
| 177 | + exit 0 # no decision; normal permission flow applies | ||||
| 178 | +} | ||||
| 179 | +``` | ||||
| 180 | + | ||||
| 181 | +Now suppose Claude Code decides to run `Bash "rm -rf /tmp/build"` against the macOS/Linux config. Here's what happens: | ||||
| 182 | + | ||||
| 183 | + | ||||
| 184 | + | ||||
| 185 | +**1. Event fires** | ||||
| 186 | + | ||||
| 187 | +The `PreToolUse` event fires. Claude Code sends the tool input as JSON on stdin to the hook: | ||||
| 188 | + | ||||
| 189 | +```json theme={null} | ||||
| 190 | +{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... } | ||||
| 191 | +``` | ||||
| 192 | + | ||||
| 193 | +**2. Matcher checks** | ||||
| 194 | + | ||||
| 195 | +The matcher `"Bash"` matches the tool name, so this hook group activates. If you omit the matcher or use `"*"`, the group activates on every occurrence of the event. | ||||
| 196 | + | ||||
| 197 | +**3. If condition checks** | ||||
| 198 | + | ||||
| 199 | +The `if` condition `"Bash(rm *)"` matches because `rm -rf /tmp/build` is a subcommand matching `rm *`, so this handler spawns. If the command had been `npm test`, the `if` check would fail and `block-rm.sh` would never run, avoiding the process spawn overhead. The `if` field is optional; without it, every handler in the matched group runs. | ||||
| 200 | + | ||||
| 201 | +**4. Hook handler runs** | ||||
| 202 | + | ||||
| 203 | +The script inspects the full command and finds `rm -rf`, so it prints a decision to stdout: | ||||
| 204 | + | ||||
| 205 | +```json theme={null} | ||||
| 206 | +{ | ||||
| 207 | + "hookSpecificOutput": { | ||||
| 208 | + "hookEventName": "PreToolUse", | ||||
| 209 | + "permissionDecision": "deny", | ||||
| 210 | + "permissionDecisionReason": "Destructive command blocked by hook" | ||||
| 211 | + } | ||||
| 212 | +} | ||||
| 213 | +``` | ||||
| 214 | + | ||||
| 215 | +If the command had been a safer `rm` variant like `rm file.txt`, the script would hit `exit 0` instead. Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal [permission flow](https://code.claude.com/docs/en/permissions.md). The hook can deny the call, but staying silent doesn't approve it. | ||||
| 216 | + | ||||
| 217 | +**5. Claude Code acts on the result** | ||||
| 218 | + | ||||
| 219 | +Claude Code reads the JSON decision, blocks the tool call, and shows Claude the reason. | ||||
| 220 | + | ||||
| 221 | +The [Configuration](#configuration) section below documents the full schema, and each [hook event](#hook-events) section documents what input your command receives and what output it can return. | ||||
| 222 | + | ||||
| 223 | +## Configuration | ||||
| 224 | + | ||||
| 225 | +Hooks are defined in JSON settings files. The configuration has three levels of nesting: | ||||
| 226 | + | ||||
| 227 | +1. Choose a [hook event](#hook-events) to respond to, like `PreToolUse` or `Stop` | ||||
| 228 | +2. Add a [matcher group](#matcher-patterns) to filter when it fires, like "only for the Bash tool" | ||||
| 229 | +3. Define one or more [hook handlers](#hook-handler-fields) to run when matched | ||||
| 230 | + | ||||
| 231 | +See [How a hook resolves](#how-a-hook-resolves) above for a complete walkthrough with an annotated example. | ||||
| 232 | + | ||||
| 233 | +> [!NOTE] | ||||
| 234 | +> | ||||
| 235 | +> This page uses specific terms for each level: **hook event** for the lifecycle point, **matcher group** for the filter, and **hook handler** for the shell command, HTTP endpoint, MCP tool, prompt, or agent that runs. "Hook" on its own refers to the general feature. | ||||
| 236 | + | ||||
| 237 | +### Hook locations | ||||
| 238 | + | ||||
| 239 | +Where you define a hook determines its scope: | ||||
| 240 | + | ||||
| 241 | +| Location | Scope | Shareable | | ||||
| 242 | +| :- | :- | :- | | ||||
| 243 | +| `~/.claude/settings.json` | All your projects | No, local to your machine | | ||||
| 244 | +| `.claude/settings.json` | Single project | Yes, can be committed to the repo | | ||||
| 245 | +| `.claude/settings.local.json` | Single project | No, gitignored when Claude Code saves a setting to it | | ||||
| 246 | +| Managed policy settings | Organization-wide | Yes, admin-controlled | | ||||
| 247 | +| [Plugin](https://code.claude.com/docs/en/plugins/overview.md) `hooks/hooks.json` | When plugin is enabled | Yes, bundled with the plugin | | ||||
| 248 | +| [Skill](https://code.claude.com/docs/en/skills.md) frontmatter | The rest of the session once the skill is invoked. See [Hooks in skills and agents](#hooks-in-skills-and-agents) | Yes, defined in the skill file | | ||||
| 249 | +| [Subagent](https://code.claude.com/docs/en/sub-agents.md) frontmatter | While that subagent is running | Yes, defined in the subagent file | | ||||
| 250 | + | ||||
| 251 | +[Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) don't read your local `~/.claude/settings.json`. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#permissions-and-tool-approval), Claude Code also runs the hooks the operator seeded from the runner host's `~/.claude/`, and it runs the hooks in the runner image's managed settings file when that file is among the [managed sources Claude Code applies](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources), which by default means only when neither server-managed settings nor an MDM-delivered Claude Code policy supplies the managed tier. See [what carries over from your setup](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup) for which settings files and plugins, and so which hooks, reach a cloud session. | ||||
| 252 | + | ||||
| 253 | +For details on settings file resolution, see [settings](https://code.claude.com/docs/en/settings.md). | ||||
| 254 | + | ||||
| 255 | +Hooks from settings files, managed policy settings, and plugins also run inside [subagents](https://code.claude.com/docs/en/sub-agents.md). When a subagent calls a tool, tool events such as `PreToolUse` and `PostToolUse` fire the same configured hooks as in the main conversation, and the input carries the `agent_id` and `agent_type` [common input fields](#common-input-fields) that identify the subagent. | ||||
| 256 | + | ||||
| 257 | +Administrators can use [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) in [managed settings](https://code.claude.com/docs/en/managed-settings.md) to restrict which hooks run: | ||||
| 258 | + | ||||
| 259 | +* Your user, project, local, and plugin hooks are blocked. Hooks from plugins force-enabled in managed settings `enabledPlugins` are exempt | ||||
| 260 | +* Claude Code also narrows your [`statusLine`](https://code.claude.com/docs/en/statusline), [`fileSuggestion`](https://code.claude.com/docs/en/settings-reference#filesuggestion), and [`subagentStatusLine`](https://code.claude.com/docs/en/statusline#subagent-status-lines) settings to managed settings | ||||
| 261 | +* Claude Code also disables plugins with a [`command` source](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source), including plugins force-enabled in managed settings `enabledPlugins`, unless [`disableCommandPluginSources`](https://code.claude.com/docs/en/settings-reference#disablecommandpluginsources) is explicitly set to `false`. `command` sources require Claude Code v2.1.229 or later | ||||
| 262 | +* Claude Code also blocks marketplace [`headersHelper` commands](https://code.claude.com/docs/en/plugins/host-marketplace#authenticate-archive-downloads) unless [`disableCommandPluginSources`](https://code.claude.com/docs/en/settings-reference#disablecommandpluginsources) is explicitly set to `false`, except for a marketplace that managed settings themselves declare | ||||
| 263 | + | ||||
| 264 | +See [what runs under `allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly). | ||||
| 265 | + | ||||
| 266 | +Hook entries merge across settings levels rather than replacing each other: user, project, and local settings add their own hooks without removing managed ones, and the [`disableAllHooks`](#disable-or-remove-hooks) setting can't disable managed hooks from outside managed settings. | ||||
| 267 | + | ||||
| 268 | +The [HTTP hook allowlists](https://code.claude.com/docs/en/settings-reference.md#hook-and-skill-settings) apply to hooks from every source, including managed policy settings: | ||||
| 269 | + | ||||
| 270 | +* `allowedHttpHookUrls`: when defined at any settings level, Claude Code runs an HTTP hook handler only if its URL matches the merged allowlist | ||||
| 271 | +* `httpHookAllowedEnvVars`: when defined, Claude Code interpolates only the environment variables on that list into hook headers | ||||
| 272 | + | ||||
| 273 | +### Matcher patterns | ||||
| 274 | + | ||||
| 275 | +The `matcher` field filters when hooks fire. How a matcher is evaluated depends on the characters it contains: | ||||
| 276 | + | ||||
| 277 | +| Matcher value | Evaluated as | Example | | ||||
| 278 | +| :- | :- | :- | | ||||
| 279 | +| `"*"`, `""`, or omitted | Match all | fires on every occurrence of the event | | ||||
| 280 | +| Only letters, digits, `_`, `-`, spaces, `,`, and `\|` | Exact string, or list of exact strings separated by `\|` or `,` with optional surrounding whitespace | `Bash` matches only the Bash tool; `Edit\|Write` and `Edit, Write` each match either tool exactly; `code-reviewer` matches only that agent type | | ||||
| 281 | +| Contains any other character | JavaScript regular expression, unanchored | `^Notebook` matches any tool whose name starts with `Notebook`; `mcp__memory__.*` matches every tool from the `memory` server | | ||||
| 282 | + | ||||
| 283 | +A matcher on the regular-expression path is tested with JavaScript's `RegExp.prototype.test`, which succeeds on a match anywhere in the value. `Edit.*` matches both `Edit` and `NotebookEdit`; wrap the pattern in `^` and `$`, as in `^Edit$`, when you need a whole-string match. | ||||
| 284 | + | ||||
| 285 | +`FileChanged` and `StopFailure` use a narrower exact-match set of letters, digits, `_`, and `|` only. A hyphen, space, or comma in a matcher for those two events keeps it on the regular-expression path, and only `|` separates alternatives. Every other event with matcher support in the table that follows accepts `|` or `,`. | ||||
| 286 | + | ||||
| 287 | +The `FileChanged` event doesn't follow these rules when building its watch list. See [FileChanged](#filechanged). | ||||
| 288 | + | ||||
| 289 | +Each event type matches on a different field: | ||||
| 290 | + | ||||
| 291 | +| Event | What the matcher filters | Example matcher values | | ||||
| 292 | +| :- | :- | :- | | ||||
| 293 | +| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` | | ||||
| 294 | +| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact`, `fork` | | ||||
| 295 | +| `Setup` | which CLI flag triggered setup | `init`, `maintenance` | | ||||
| 296 | +| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` | | ||||
| 297 | +| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` | | ||||
| 298 | +| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, custom agent names, or plugin-scoped names like `^my-plugin:reviewer$` | | ||||
| 299 | +| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` | | ||||
| 300 | +| `PreModelSwitch`, `PostModelSwitch` | canonical name of the model the session switches to, as described under [PreModelSwitch](#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` | | ||||
| 301 | +| `SubagentStop` | agent type | same values as `SubagentStart` | | ||||
| 302 | +| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | | ||||
| 303 | +| `CwdChanged` | no matcher support | always fires on every occurrence | | ||||
| 304 | +| `DirectoryAdded` | how the directory was added | `slash_command`, `register_repo_root` | | ||||
| 305 | +| `FileChanged` | literal filenames to watch (see [FileChanged](#filechanged)) | `.envrc\|.env` | | ||||
| 306 | +| `StopFailure` | error type | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, `unknown` | | ||||
| 307 | +| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` | | ||||
| 308 | +| `UserPromptExpansion` | command name | your skill or command names | | ||||
| 309 | +| `Elicitation` | MCP server name | your configured MCP server names | | ||||
| 310 | +| `ElicitationResult` | MCP server name | same values as `Elicitation` | | ||||
| 311 | +| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` | no matcher support | always fires on every occurrence | | ||||
| 312 | + | ||||
| 313 | +Matching `StopFailure` on `cloud_credential_error` requires Claude Code v2.1.267 or later, the first version that reports credential-load failures under that value rather than `server_error` or `unknown`. | ||||
| 314 | + | ||||
| 315 | +For most events, Claude Code evaluates the matcher against a field from the [JSON input](#hook-input-and-output) it sends to your hook on stdin. For tool events, that field is `tool_name`. For `PreModelSwitch` and `PostModelSwitch`, Claude Code evaluates the matcher against the canonical name it derives from `to_model`, as described under [PreModelSwitch](#premodelswitch). Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event. | ||||
| 316 | + | ||||
| 317 | +This example runs a linting script only when Claude writes or edits a file: | ||||
| 318 | + | ||||
| 319 | +```json theme={null} | ||||
| 320 | +{ | ||||
| 321 | + "hooks": { | ||||
| 322 | + "PostToolUse": [ | ||||
| 323 | + { | ||||
| 324 | + "matcher": "Edit|Write", | ||||
| 325 | + "hooks": [ | ||||
| 326 | + { | ||||
| 327 | + "type": "command", | ||||
| 328 | + "command": "/path/to/lint-check.sh" | ||||
| 329 | + } | ||||
| 330 | + ] | ||||
| 331 | + } | ||||
| 332 | + ] | ||||
| 333 | + } | ||||
| 334 | +} | ||||
| 335 | +``` | ||||
| 336 | + | ||||
| 337 | +If you add a `matcher` field to an event without matcher support, it is silently ignored. | ||||
| 338 | + | ||||
| 339 | +For tool events, you can filter more narrowly by setting the [`if` field](#common-fields) on individual hook handlers. `if` uses [permission rule syntax](https://code.claude.com/docs/en/permissions.md) to match against the tool name and arguments together, so `"Bash(git *)"` runs when any subcommand of the Bash input matches `git *` and `"Edit(*.ts)"` runs only for TypeScript files. | ||||
| 340 | + | ||||
| 341 | +#### Match MCP tools | ||||
| 342 | + | ||||
| 343 | +[MCP](https://code.claude.com/docs/en/mcp.md) server tools appear as regular tools in tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`), so you can match them the same way you match any other tool name. | ||||
| 344 | + | ||||
| 345 | +MCP tools follow the naming pattern `mcp__<server>__<tool>`, for example: | ||||
| 346 | + | ||||
| 347 | +* `mcp__memory__create_entities`: Memory server's create entities tool | ||||
| 348 | +* `mcp__filesystem__read_file`: Filesystem server's read file tool | ||||
| 349 | +* `mcp__github__search_repositories`: GitHub server's search tool | ||||
| 350 | + | ||||
| 351 | +To match every tool from a server, append `.*` to the server prefix. The `.*` is required: a matcher like `mcp__memory` or `mcp__brave-search` contains only exact-match characters, so it is compared as an exact string and matches no tool. | ||||
| 352 | + | ||||
| 353 | +* `mcp__memory__.*` matches all tools from the `memory` server | ||||
| 354 | +* `mcp__brave-search__.*` matches all tools from a server whose name contains a hyphen | ||||
| 355 | +* `mcp__.*__write.*` matches any tool whose name starts with `write` from any server | ||||
| 356 | + | ||||
| 357 | +Tools from a [plugin-bundled MCP server](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) use a scoped server segment that includes the plugin name: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. A matcher written against the bare server key never fires for these tools. For a plugin named `my-plugin` that bundles a server under the key `db`, a `query` tool appears as `mcp__plugin_my-plugin_db__query`, so the matcher for every tool from that server is `mcp__plugin_my-plugin_db__.*`. Use the same scoped tool name in a handler's [`if` field](#common-fields). See [Plugin-provided MCP servers](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) for how the scoped name is built. | ||||
| 358 | + | ||||
| 359 | +This example logs all memory server operations and validates write operations from any MCP server: | ||||
| 360 | + | ||||
| 361 | +```json theme={null} | ||||
| 362 | +{ | ||||
| 363 | + "hooks": { | ||||
| 364 | + "PreToolUse": [ | ||||
| 365 | + { | ||||
| 366 | + "matcher": "mcp__memory__.*", | ||||
| 367 | + "hooks": [ | ||||
| 368 | + { | ||||
| 369 | + "type": "command", | ||||
| 370 | + "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log" | ||||
| 371 | + } | ||||
| 372 | + ] | ||||
| 373 | + }, | ||||
| 374 | + { | ||||
| 375 | + "matcher": "mcp__.*__write.*", | ||||
| 376 | + "hooks": [ | ||||
| 377 | + { | ||||
| 378 | + "type": "command", | ||||
| 379 | + "command": "/home/user/scripts/validate-mcp-write.py" | ||||
| 380 | + } | ||||
| 381 | + ] | ||||
| 382 | + } | ||||
| 383 | + ] | ||||
| 384 | + } | ||||
| 385 | +} | ||||
| 386 | +``` | ||||
| 387 | + | ||||
| 388 | +### Hook handler fields | ||||
| 389 | + | ||||
| 390 | +Each object in the inner `hooks` array is a hook handler: the shell command, HTTP endpoint, MCP tool, LLM prompt, or agent that runs when the matcher matches. There are five types: | ||||
| 391 | + | ||||
| 392 | +* **[Command hooks](#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout. | ||||
| 393 | +* **[HTTP hooks](#http-hook-fields)** (`type: "http"`): send the event's JSON input as an HTTP POST request to a URL. The endpoint communicates results back through the response body using the same [JSON output format](#json-output) as command hooks. | ||||
| 394 | +* **[MCP tool hooks](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): call a tool on a configured [MCP server](https://code.claude.com/docs/en/mcp.md). The tool's text output is treated like command-hook stdout. | ||||
| 395 | +* **[Prompt hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns its decision as JSON. See [Prompt-based hooks](#prompt-based-hooks). | ||||
| 396 | +* **[Agent hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks). | ||||
| 397 | + | ||||
| 398 | +When an event fires, its matching hooks run in parallel. If more than 12 of them are prompt or agent hooks, 12 of those run at once and the rest start as running ones finish. Each waiting hook's [`timeout`](#common-fields) starts counting when that hook starts. | ||||
| 399 | + | ||||
| 400 | +If you define the same handler in more than one settings file, it runs once. A plugin's or skill's copy of the same handler stays separate. | ||||
| 401 | + | ||||
| 402 | +Handlers run in the current directory with Claude Code's environment. If the current directory no longer exists, for example a worktree or temp directory that another shell deleted mid-session, Claude Code runs command hooks from the first of these that still exists: the directory the session started in, the project root, your home directory, or the system temp directory. Claude Code records a warning naming the fallback directory in the [debug log](#debug-hooks). For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout). | ||||
| 403 | + | ||||
| 404 | +The `$CLAUDE_CODE_REMOTE` environment variable is `"true"` in remote web environments and not set in the local CLI. Claude Code v2.1.199 and later sets [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](https://code.claude.com/docs/en/env-vars) to the [Remote Control](https://code.claude.com/docs/en/remote-control.md) session ID while the local session has an active Remote Control connection. | ||||
| 405 | + | ||||
| 406 | +#### Common fields | ||||
| 407 | + | ||||
| 408 | +These fields apply to all hook types: | ||||
| 409 | + | ||||
| 410 | +| Field | Required | Description | | ||||
| 411 | +| :- | :- | :- | | ||||
| 412 | +| `type` | yes | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"`, or `"agent"` | | ||||
| 413 | +| `if` | no | [Permission rule syntax](https://code.claude.com/docs/en/permissions.md#permission-rule-syntax) to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook command only runs if the tool call matches the pattern. See the [Bash matching table](#bash-if-matching) for how Bash patterns evaluate against subcommands, `$()`, and backticks. Only evaluated on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied`. On other events, a hook with `if` set never runs | | ||||
| 414 | +| `timeout` | no | Seconds before canceling. Claude Code doesn't enforce it on a command hook you run with [`async: true`](#run-hooks-in-the-background). Defaults: 600 for `command`, `http`, and `mcp_tool`; 30 for `prompt`; 60 for `agent`. Claude Code lowers the `command`, `http`, and `mcp_tool` default to 30 on [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch), and [`PostModelSwitch`](#postmodelswitch), and to 10 on [`MessageDisplay`](#messagedisplay). [`SessionEnd`](#sessionend) hooks share a 1.5-second budget; if your settings set a longer per-hook `timeout`, Claude Code raises the budget to match, up to 60 seconds | | ||||
| 415 | +| `statusMessage` | no | Custom spinner message displayed while the hook runs | | ||||
| 416 | +| `once` | no | If `true`, Claude Code removes the hook after its first successful run. A run that fails, blocks with exit code 2, or times out leaves the hook in place, so it runs again on the next matching event. Only honored for hooks declared in [skill frontmatter](#hooks-in-skills-and-agents); ignored in settings files and agent frontmatter | | ||||
| 417 | + | ||||
| 418 | +The `if` field holds exactly one permission rule. There is no `&&`, `||`, or list syntax for combining rules; to apply multiple conditions, define a separate hook handler for each. | ||||
| 419 | + | ||||
| 420 | +In an `if` condition for a file tool, a single-segment directory pattern like `"Edit(src/**)"` matches only the `src` directory in the working directory and the files under it. To match a directory named `src` at any depth, write `"Edit(**/src/**)"`. | ||||
| 421 | + | ||||
| 422 | +#### How `if` patterns match Bash commands | ||||
| 423 | + | ||||
| 424 | +For Bash patterns in the [`if` field](#common-fields), whether your hook command runs depends on the shape of the pattern and the Bash command Claude is invoking. Leading `VAR=value` assignments are stripped before matching. | ||||
| 425 | + | ||||
| 426 | +| `if` pattern | Bash command | Hook runs? | Why | | ||||
| 427 | +| :- | :- | :- | :- | | ||||
| 428 | +| `Bash(git *)` | `FOO=bar git push` | yes | leading assignments are stripped; `git push` matches | | ||||
| 429 | +| `Bash(git *)` | `npm test && git push` | yes | each subcommand is checked; `git push` matches | | ||||
| 430 | +| `Bash(rm *)` | `echo $(rm -rf /)` | yes | commands inside `$()` and backticks are checked; `rm -rf /` matches | | ||||
| 431 | +| `Bash(rm *)` | `echo $(date)` | no | no subcommand matches `rm *` | | ||||
| 432 | +| `Bash(git push *)` | `echo $(date)` | yes | patterns that specify more than the command name run the hook anyway on `$()`, backticks, or `$VAR` | | ||||
| 433 | + | ||||
| 434 | +When Claude Code can't determine which commands the Bash input runs, it runs your hook regardless of the pattern. Because the `if` filter is best-effort, use the [permission system](https://code.claude.com/docs/en/permissions.md) rather than a hook to enforce a hard allow or deny. | ||||
| 435 | + | ||||
| 436 | +#### Command hook fields | ||||
| 437 | + | ||||
| 438 | +In addition to the [common fields](#common-fields), command hooks accept these fields: | ||||
| 439 | + | ||||
| 440 | +| Field | Required | Description | | ||||
| 441 | +| :- | :- | :- | | ||||
| 442 | +| `command` | yes | Shell command to execute. With `args`, the executable to spawn directly. See [Exec form and shell form](#exec-form-and-shell-form) | | ||||
| 443 | +| `args` | no | Argument list. When present, `command` is resolved as an executable and spawned directly with `args` as the argument vector, with no shell involved. See [Exec form and shell form](#exec-form-and-shell-form) | | ||||
| 444 | +| `async` | no | If `true`, runs in the background without blocking. See [Run hooks in the background](#run-hooks-in-the-background) | | ||||
| 445 | +| `asyncRewake` | no | If `true`, runs in the background and wakes Claude on exit code 2. The hook's stderr, or stdout if stderr is empty, is shown to Claude as a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder) so it can react to a long-running background failure | | ||||
| 446 | +| `shell` | no | Shell to use for this hook. Accepts `"bash"` or `"powershell"`. Defaults to `"bash"`, or to `"powershell"` on Windows when Git Bash isn't installed. Setting `"powershell"` runs the command via PowerShell on Windows. Does not require `CLAUDE_CODE_USE_POWERSHELL_TOOL` since hooks spawn PowerShell directly. Ignored when `args` is set | | ||||
| 447 | +| `onFailure` | no | Whether the action that triggered the hook goes ahead when the hook fails: `"continue"` or `"block"`. See [Block the action when a hook fails](#block-the-action-when-a-hook-fails) for `"block"` and for leaving the field unset. Requires Claude Code v2.1.295 or later | | ||||
| 448 | + | ||||
| 449 | +##### Exec form and shell form | ||||
| 450 | + | ||||
| 451 | +A command hook runs as exec form when `args` is set, and shell form when `args` is omitted. Set `args` whenever the hook references a [path placeholder](#reference-scripts-by-path), since each element is passed as one argument with no quoting. Omit `args` when you need shell features like pipes or `&&`, or when neither concern applies. | ||||
| 452 | + | ||||
| 453 | +**Exec form** runs when `args` is present. Claude Code resolves `command` as an executable on `PATH` and spawns it directly with `args` as the argument vector. There is no shell, so each `args` element is one argument exactly as written, and path placeholders like `${CLAUDE_PLUGIN_ROOT}` are substituted into `command` and into each `args` element as plain strings. Special characters such as apostrophes, `$`, and backticks pass through verbatim because there is no shell to interpret them. No shell tokenization happens on any platform. | ||||
| 454 | + | ||||
| 455 | +**Shell form** runs when `args` is absent. The `command` string is passed to a shell: `sh -c` on macOS and Linux, Git Bash on Windows, or PowerShell when Git Bash isn't installed. Set the `shell` field to choose explicitly. The shell tokenizes the string, expands variables, and interprets pipes, `&&`, redirects, and globs. | ||||
| 456 | + | ||||
| 457 | +> [!NOTE] | ||||
| 458 | +> | ||||
| 459 | +> On Windows, exec form requires `command` to resolve to a real executable such as a `.exe`. The `.cmd` and `.bat` shims that npm, npx, eslint, and other tools install in `node_modules/.bin` are not executables and can't be spawned without a shell. To run them in exec form, invoke the underlying script with `node` directly, for example `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`. The `node` plus script-path pattern works on every platform because `node.exe` is a real binary. To run a `.cmd` or `.bat` shim by name, use shell form. | ||||
| 460 | + | ||||
| 461 | +This example runs a Node script bundled with a plugin. Exec form passes the resolved script path as one argument with no quoting: | ||||
| 462 | + | ||||
| 463 | +```json theme={null} | ||||
| 464 | +{ | ||||
| 465 | + "type": "command", | ||||
| 466 | + "command": "node", | ||||
| 467 | + "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"] | ||||
| 468 | +} | ||||
| 469 | +``` | ||||
| 470 | + | ||||
| 471 | +The equivalent shell form needs quoting to handle paths with spaces or special characters: | ||||
| 472 | + | ||||
| 473 | +```json theme={null} | ||||
| 474 | +{ | ||||
| 475 | + "type": "command", | ||||
| 476 | + "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix" | ||||
| 477 | +} | ||||
| 478 | +``` | ||||
| 479 | + | ||||
| 480 | +Both forms support the same [path placeholders](#reference-scripts-by-path), and both export them as the environment variables `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, and `CLAUDE_PLUGIN_DATA` on the spawned process, so a script can read `process.env.CLAUDE_PLUGIN_ROOT` regardless of how it was launched. | ||||
| 481 | + | ||||
| 482 | +Plugin hooks additionally substitute [`${user_config.*}`](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration) values, in exec form only: the value is substituted into `command` and into each `args` element as a plain string, so no shell re-parses it. | ||||
| 483 | + | ||||
| 484 | +A shell-form plugin hook whose `command` references `${user_config.*}` fails with an [error](https://code.claude.com/docs/en/errors.md#plugin-command-references-user-config) instead of running. To use an option value from a shell-form hook, read the `$CLAUDE_PLUGIN_OPTION_<KEY>` environment variable, such as `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` for a `webhook_url` option, or set `args` to switch the hook to exec form. Before v2.1.207, shell-form plugin hook commands also substituted `${user_config.*}`. | ||||
| 485 | + | ||||
| 486 | +> [!NOTE] | ||||
| 487 | +> | ||||
| 488 | +> In exec form, `command` is the executable name or path only. If `command` is a bare name with no path separator and contains whitespace alongside `args`, Claude Code logs a warning because the spawn will fail: there is no executable named `node script.js`. Move the extra tokens into `args`. Absolute paths with spaces, such as `C:\Program Files\nodejs\node.exe`, are a single valid executable and don't trigger the warning. | ||||
| 489 | + | ||||
| 490 | +#### HTTP hook fields | ||||
| 491 | + | ||||
| 492 | +In addition to the [common fields](#common-fields), HTTP hooks accept these fields: | ||||
| 493 | + | ||||
| 494 | +| Field | Required | Description | | ||||
| 495 | +| :- | :- | :- | | ||||
| 496 | +| `url` | yes | URL to send the POST request to | | ||||
| 497 | +| `headers` | no | Additional HTTP headers as key-value pairs. Values support environment variable interpolation using `$VAR_NAME` or `${VAR_NAME}` syntax. Only variables listed in `allowedEnvVars` are resolved | | ||||
| 498 | +| `allowedEnvVars` | no | List of environment variable names that may be interpolated into header values. References to unlisted variables are replaced with empty strings. Required for any env var interpolation to work | | ||||
| 499 | +| `onFailure` | no | What happens to the action when the hook fails: `"continue"`, the default, or `"block"`. See [Block the action when a hook fails](#block-the-action-when-a-hook-fails). Requires Claude Code v2.1.295 or later | | ||||
| 500 | + | ||||
| 501 | +Claude Code sends the hook's [JSON input](#hook-input-and-output) as the POST request body with `Content-Type: application/json`. The response body uses the same [JSON output format](#json-output) as command hooks. | ||||
| 502 | + | ||||
| 503 | +Error handling differs from command hooks; see [HTTP response handling](#http-response-handling). | ||||
| 504 | + | ||||
| 505 | +This example sends `PreToolUse` events to a local validation service, authenticating with a token from the `MY_TOKEN` environment variable: | ||||
| 506 | + | ||||
| 507 | +```json theme={null} | ||||
| 508 | +{ | ||||
| 509 | + "hooks": { | ||||
| 510 | + "PreToolUse": [ | ||||
| 511 | + { | ||||
| 512 | + "matcher": "Bash", | ||||
| 513 | + "hooks": [ | ||||
| 514 | + { | ||||
| 515 | + "type": "http", | ||||
| 516 | + "url": "http://localhost:8080/hooks/pre-tool-use", | ||||
| 517 | + "timeout": 30, | ||||
| 518 | + "headers": { | ||||
| 519 | + "Authorization": "Bearer $MY_TOKEN" | ||||
| 520 | + }, | ||||
| 521 | + "allowedEnvVars": ["MY_TOKEN"] | ||||
| 522 | + } | ||||
| 523 | + ] | ||||
| 524 | + } | ||||
| 525 | + ] | ||||
| 526 | + } | ||||
| 527 | +} | ||||
| 528 | +``` | ||||
| 529 | + | ||||
| 530 | +#### MCP tool hook fields | ||||
| 531 | + | ||||
| 532 | +In addition to the [common fields](#common-fields), MCP tool hooks accept these fields: | ||||
| 533 | + | ||||
| 534 | +| Field | Required | Description | | ||||
| 535 | +| :- | :- | :- | | ||||
| 536 | +| `server` | yes | Name of a configured MCP server. For a [plugin-bundled server](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers), this is the scoped name `plugin:<plugin-name>:<server-name>`, such as `plugin:my-plugin:db`, not the bare server key | | ||||
| 537 | +| `tool` | yes | Name of the tool to call on that server | | ||||
| 538 | +| `input` | no | Arguments passed to the tool. String values support `${path}` substitution from the hook's [JSON input](#hook-input-and-output), such as `"${tool_input.file_path}"` | | ||||
| 539 | + | ||||
| 540 | +This example calls the `security_scan` tool on the `my_server` MCP server after each `Write` or `Edit`, passing the edited file's path: | ||||
| 541 | + | ||||
| 542 | +```json theme={null} | ||||
| 543 | +{ | ||||
| 544 | + "hooks": { | ||||
| 545 | + "PostToolUse": [ | ||||
| 546 | + { | ||||
| 547 | + "matcher": "Write|Edit", | ||||
| 548 | + "hooks": [ | ||||
| 549 | + { | ||||
| 550 | + "type": "mcp_tool", | ||||
| 551 | + "server": "my_server", | ||||
| 552 | + "tool": "security_scan", | ||||
| 553 | + "input": { "file_path": "${tool_input.file_path}" } | ||||
| 554 | + } | ||||
| 555 | + ] | ||||
| 556 | + } | ||||
| 557 | + ] | ||||
| 558 | + } | ||||
| 559 | +} | ||||
| 560 | +``` | ||||
| 561 | + | ||||
| 562 | +##### How the tool's result is read | ||||
| 563 | + | ||||
| 564 | +Claude Code reads the tool's text content the same way it reads command-hook stdout, following the [parsing rule under exit code 0](#exit-code-0). If the tool returns `isError: true`, the hook produces a non-blocking error and execution continues. | ||||
| 565 | + | ||||
| 566 | +##### When the server is still connecting | ||||
| 567 | + | ||||
| 568 | +On events where a hook can block or change the result, such as `PreToolUse` or `Stop`, Claude Code waits for a connecting server before it calls the tool, for at most [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) and within the hook's own [`timeout`](#common-fields). On observational events, such as `Notification` or `SessionEnd`, it doesn't wait. | ||||
| 569 | + | ||||
| 570 | +A server showing the [`cached` status](https://code.claude.com/docs/en/mcp#server-status-detail) connects when the hook calls its tool. If the server isn't connected at that point, the hook produces a non-blocking error and execution continues. The hook never starts an OAuth flow, so [authenticate the server from `/mcp`](https://code.claude.com/docs/en/mcp#authenticate-with-remote-mcp-servers) first. | ||||
| 571 | + | ||||
| 572 | +##### Events that fire before MCP servers are available | ||||
| 573 | + | ||||
| 574 | +`SessionStart` at launch, including with `--continue` or `--resume`, and every `Setup` event fire before the session's MCP servers are available to hooks. Claude Code skips their `mcp_tool` hooks without calling the tool, and the [debug log](#debug-hooks) records `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`, or the same message naming `Setup`. When `SessionStart` fires again later in the session, after `/clear` or a compaction, its `mcp_tool` hooks run. For anything the session needs at launch, use a `type: "command"` hook on `SessionStart` instead. | ||||
| 575 | + | ||||
| 576 | +#### Prompt and agent hook fields | ||||
| 577 | + | ||||
| 578 | +In addition to the [common fields](#common-fields), prompt and agent hooks accept these fields: | ||||
| 579 | + | ||||
| 580 | +| Field | Required | Description | | ||||
| 581 | +| :- | :- | :- | | ||||
| 582 | +| `prompt` | yes | Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON. Escape with a backslash to include literal text: `\$1.00` renders as `$1.00` | | ||||
| 583 | +| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](https://code.claude.com/docs/en/costs.md#background-token-usage) | | ||||
| 584 | + | ||||
| 585 | +### Reference scripts by path | ||||
| 586 | + | ||||
| 587 | +Use these placeholders to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs: | ||||
| 588 | + | ||||
| 589 | +* `${CLAUDE_PROJECT_DIR}`: the project root where the session started. Claude Code also sets this variable in the environment of [stdio MCP servers](https://code.claude.com/docs/en/mcp.md#option-3-add-a-local-stdio-server) and plugin LSP servers. | ||||
| 590 | +* `${CLAUDE_PLUGIN_ROOT}`: the plugin's installation directory, for scripts bundled with a [plugin](https://code.claude.com/docs/en/plugins/overview.md). See [plugin environment variables](https://code.claude.com/docs/en/plugins/manifest-reference.md#environment-variables) for how the path behaves across updates. | ||||
| 591 | +* `${CLAUDE_PLUGIN_DATA}`: the plugin's [persistent data directory](https://code.claude.com/docs/en/plugins/components.md#path-variables-and-persistent-data), for dependencies and state that should survive plugin updates. | ||||
| 592 | + | ||||
| 593 | +> [!NOTE] | ||||
| 594 | +> | ||||
| 595 | +> **Worktrees are different.** If Claude enters a [worktree](https://code.claude.com/docs/en/worktrees.md) during the session, Claude Code keeps `${CLAUDE_PROJECT_DIR}` where it was and passes the worktree path to your hooks a different way: | ||||
| 596 | +> | ||||
| 597 | +> * **`${CLAUDE_PROJECT_DIR}` stays put**: it still points at the project root where the session started, so a command such as `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` still runs the script in the main checkout. | ||||
| 598 | +> * **`cwd` follows Claude**: the `cwd` field in the hook's [input JSON](#common-input-fields) is the worktree root after Claude enters a worktree, and the new directory after Claude runs `cd`. Read it when a hook needs to know which directory Claude is working in. | ||||
| 599 | +> | ||||
| 600 | +> For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout) for where `${CLAUDE_PROJECT_DIR}` points. | ||||
| 601 | + | ||||
| 602 | +Prefer [exec form](#exec-form-and-shell-form) for any hook that references a path placeholder. In shell form, wrap each placeholder in double quotes. | ||||
| 603 | + | ||||
| 604 | +**Project scripts** | ||||
| 605 | + | ||||
| 606 | +This example uses `${CLAUDE_PROJECT_DIR}` to run a style checker from the project's `.claude/hooks/` directory after any `Write` or `Edit` tool call: | ||||
| 607 | + | ||||
| 608 | +```json theme={null} | ||||
| 609 | +{ | ||||
| 610 | + "hooks": { | ||||
| 611 | + "PostToolUse": [ | ||||
| 612 | + { | ||||
| 613 | + "matcher": "Write|Edit", | ||||
| 614 | + "hooks": [ | ||||
| 615 | + { | ||||
| 616 | + "type": "command", | ||||
| 617 | + "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh", | ||||
| 618 | + "args": [] | ||||
| 619 | + } | ||||
| 620 | + ] | ||||
| 621 | + } | ||||
| 622 | + ] | ||||
| 623 | + } | ||||
| 624 | +} | ||||
| 625 | +``` | ||||
| 626 | + | ||||
| 627 | +**Plugin scripts** | ||||
| 628 | + | ||||
| 629 | +Define plugin hooks in `hooks/hooks.json` with an optional top-level `description` field. When a plugin is enabled, its hooks merge with your user and project hooks. | ||||
| 630 | + | ||||
| 631 | +This example runs a formatting script bundled with the plugin: | ||||
| 632 | + | ||||
| 633 | +```json theme={null} | ||||
| 634 | +{ | ||||
| 635 | + "description": "Automatic code formatting", | ||||
| 636 | + "hooks": { | ||||
| 637 | + "PostToolUse": [ | ||||
| 638 | + { | ||||
| 639 | + "matcher": "Write|Edit", | ||||
| 640 | + "hooks": [ | ||||
| 641 | + { | ||||
| 642 | + "type": "command", | ||||
| 643 | + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh", | ||||
| 644 | + "args": [], | ||||
| 645 | + "timeout": 30 | ||||
| 646 | + } | ||||
| 647 | + ] | ||||
| 648 | + } | ||||
| 649 | + ] | ||||
| 650 | + } | ||||
| 651 | +} | ||||
| 652 | +``` | ||||
| 653 | + | ||||
| 654 | +See the [plugin components reference](https://code.claude.com/docs/en/plugins/components.md#hooks) for details on creating plugin hooks. | ||||
| 655 | + | ||||
| 656 | +### Hooks in skills and agents | ||||
| 657 | + | ||||
| 658 | +In addition to settings files and plugins, hooks can be defined directly in [skills](https://code.claude.com/docs/en/skills.md) and [subagents](https://code.claude.com/docs/en/sub-agents.md) using frontmatter, in the same configuration format as settings-based hooks. How long Claude Code keeps them registered depends on the component: | ||||
| 659 | + | ||||
| 660 | +* **Subagent hooks**: Claude Code runs them only while that subagent is running and removes them when it finishes. Claude Code converts a `Stop` hook here to `SubagentStop`, the event it fires when a subagent completes. | ||||
| 661 | +* **Skill hooks**: Claude Code registers them when you or Claude invoke the skill and keeps running them for the rest of the session, on turns after the skill's own turn as well. To have Claude Code remove a hook after its first successful run instead, set [`once: true`](#common-fields) on it. | ||||
| 662 | + | ||||
| 663 | +This skill defines a `PreToolUse` hook that runs a security validation script before each `Bash` command: | ||||
| 664 | + | ||||
| 665 | +```yaml theme={null} | ||||
| 666 | +--- | ||||
| 667 | +name: secure-operations | ||||
| 668 | +description: Perform operations with security checks | ||||
| 669 | +hooks: | ||||
| 670 | + PreToolUse: | ||||
| 671 | + - matcher: "Bash" | ||||
| 672 | + hooks: | ||||
| 673 | + - type: command | ||||
| 674 | + command: "./scripts/security-check.sh" | ||||
| 675 | +--- | ||||
| 676 | +``` | ||||
| 677 | + | ||||
| 678 | +Subagents use the same format in their YAML frontmatter. | ||||
| 679 | + | ||||
| 680 | +Frontmatter hooks in a project skill follow the same [workspace trust rule as hooks in settings files](#workspace-trust). Claude Code registers them when you or Claude invoke the skill, including in a `-p` run in a folder you haven't trusted. | ||||
| 681 | + | ||||
| 682 | +Frontmatter hooks in a project subagent run only after you accept the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder the agent file came from. A `-p` session doesn't count as accepting it. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) compares this with the settings-file rule, and the subagents page lists [which scopes are exempt](https://code.claude.com/docs/en/sub-agents.md#hooks-in-subagent-frontmatter). | ||||
| 683 | + | ||||
| 684 | +#### Limits on skill hooks | ||||
| 685 | + | ||||
| 686 | +When a skill's frontmatter hooks don't fire after you or Claude invoke the skill, run [`/hooks`](#the-%2Fhooks-menu) in that session. If it lists them, see [Hook not firing](https://code.claude.com/docs/en/hooks-guide.md#hook-not-firing). If it lists none of them, the skill may be under a plugin-only lock or past a hook limit, and runs without any of its frontmatter hooks. Check for each case: | ||||
| 687 | + | ||||
| 688 | +* **Plugin-only lock**: your organization's administrator can lock hooks to plugins and managed settings with the [`strictPluginOnlyCustomization`](https://code.claude.com/docs/en/settings-reference#strictpluginonlycustomization-hooks) managed setting. A skill keeps its frontmatter hooks under that lock only if it's a plugin skill, a [bundled skill](https://code.claude.com/docs/en/skills.md#bundled-skills), or a skill in the [managed settings directory](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms). The hooks in your own settings files don't run either. | ||||
| 689 | + * **Check**: type `/status` in a Claude Code session. If the [`Setting sources` line](https://code.claude.com/docs/en/settings#check-what-your-organization-enforces) includes `Enterprise managed settings`, ask your administrator whether `strictPluginOnlyCustomization` locks hooks. | ||||
| 690 | + * **Fix**: move the skill into a [plugin](https://code.claude.com/docs/en/plugins/create.md#convert-an-existing-claude-setup), because plugin skills keep their frontmatter hooks. List the plugin in a [marketplace](https://code.claude.com/docs/en/plugins/create-marketplace.md#create-a-marketplace), then install it from there. If Claude Code refuses the marketplace with [`is blocked by enterprise policy`](https://code.claude.com/docs/en/plugins/troubleshooting#marketplace-source-is-blocked-by-enterprise-policy), ask your administrator to allow that marketplace. | ||||
| 691 | +* **Hook limit**: in Claude Code v2.1.304 or later, each source of skills has its own limit per session. Your project, your personal skills folder, and each plugin count as separate sources. The skills from one source can register at most 1,024 hooks. Those hooks' matchers can total at most 16,384 characters. A matcher with several hooks under it counts once for each hook. | ||||
| 692 | + * **Check**: repeat the session where the hook didn't fire, with debug logging on: | ||||
| 693 | + 1. Start a new session from your shell with `claude --debug`. If you don't start sessions from a shell, type [`/debug`](https://code.claude.com/docs/en/commands#all-commands) first in the new session instead. | ||||
| 694 | + 2. Invoke the same skills in the same order, including the ones Claude invoked, because both totals build up skill by skill. Ask Claude to invoke any skill you can't type as a command. | ||||
| 695 | + 3. Search the [debug log](#debug-hooks) for `registers none of its hooks`. A line containing that text names the skill that went past the limit. | ||||
| 696 | + * **Fix**: declare fewer hooks or shorter matchers in that skill or in the other skills from its source, then start a new session. If those skills aren't yours to edit, ask their author for that change. Until then, start a new session and invoke the skill you need before any other skill from its source. | ||||
| 697 | + | ||||
| 698 | +If neither case is yours, check for [frontmatter that didn't parse](https://code.claude.com/docs/en/skills.md#skill-not-triggering). | ||||
| 699 | + | ||||
| 700 | +### The `/hooks` menu | ||||
| 701 | + | ||||
| 702 | +Type `/hooks` in Claude Code to open a read-only browser for your configured hooks. The list labels each hook with where it comes from, such as user settings, project settings, local settings, a plugin, or the current session. | ||||
| 703 | + | ||||
| 704 | +Select a hook to see the full text of what it runs and where it's defined, such as the path of its settings file or the name of its plugin. | ||||
| 705 | + | ||||
| 706 | +To browse all hook events, including ones with no hooks configured, select `All events` at the end of the list. | ||||
| 707 | + | ||||
| 708 | +### Disable or remove hooks | ||||
| 709 | + | ||||
| 710 | +To remove a hook defined in a settings file, delete its entry from that file. | ||||
| 711 | + | ||||
| 712 | +To temporarily disable all hooks without removing them, set `"disableAllHooks": true` in your settings file. Claude Code reads the value left after [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) applies, so a `"disableAllHooks": false` in a project's `.claude/settings.json` overrides a `true` in your user settings. To turn hooks off for one run whatever the project's settings say, pass `--settings '{"disableAllHooks": true}'`, which takes precedence over project and local settings. There is no way to disable an individual hook while keeping it in the configuration. | ||||
| 713 | + | ||||
| 714 | +The `disableAllHooks` setting respects the managed settings hierarchy. If an administrator has configured hooks through managed policy settings, `disableAllHooks` set in user, project, or local settings can't disable those managed hooks. Only `disableAllHooks` set at the managed settings level can disable managed hooks. For the full reach of each level, see [`disableAllHooks`](https://code.claude.com/docs/en/settings-reference#disableallhooks). | ||||
| 715 | + | ||||
| 716 | +Direct edits to hooks in settings files are normally picked up automatically by the file watcher. | ||||
| 717 | + | ||||
| 718 | +## Hook input and output | ||||
| 719 | + | ||||
| 720 | +Command hooks receive JSON data via stdin and communicate results through exit codes, stdout, and stderr. HTTP hooks receive the same JSON as the POST request body and communicate results through the HTTP response body. This section covers fields and behavior common to all events. Each event's section under [Hook events](#hook-events) includes its specific input schema and decision control options. | ||||
| 721 | + | ||||
| 722 | +On macOS and Linux, command hooks run in their own session without a controlling terminal. The hook process and any child processes can't open `/dev/tty` or send escape sequences directly to the Claude Code interface. Windows has no `/dev/tty`. | ||||
| 723 | + | ||||
| 724 | +To surface a message to the user on any platform, return [`systemMessage`](#json-output) in JSON output. Some events discard it or deliver it elsewhere, and each [event's section](#hook-events) says so. To trigger a desktop notification, set a window title, or ring the bell, return [`terminalSequence`](#emit-terminal-notifications) instead. | ||||
| 725 | + | ||||
| 726 | +### Common input fields | ||||
| 727 | + | ||||
| 728 | +Hook events receive these fields as JSON, in addition to event-specific fields documented in each [hook event](#hook-events) section. For command hooks, this JSON arrives via stdin. For HTTP hooks, it arrives as the POST request body. | ||||
| 729 | + | ||||
| 730 | +| Field | Description | | ||||
| 731 | +| :- | :- | | ||||
| 732 | +| `session_id` | Current session identifier | | ||||
| 733 | +| `prompt_id` | UUID identifying the user prompt currently being processed. Matches the [`prompt.id` attribute on OpenTelemetry events](https://code.claude.com/docs/en/monitoring-usage#event-correlation-attributes), so you can correlate hook output with telemetry for a single prompt. Absent until the first user input | | ||||
| 734 | +| `transcript_path` | Path to conversation JSON. The transcript file is written asynchronously and may lag the in-memory conversation, so it may not yet include the current turn's most recent messages when a hook fires. Hooks that need the final assistant text of the current turn should use `last_assistant_message` on [Stop](#stop) and [SubagentStop](#subagentstop) instead of reading the transcript | | ||||
| 735 | +| `cwd` | Current working directory when the hook is invoked | | ||||
| 736 | +| `scratchpad_dir` | Path to the session's [scratchpad directory](https://code.claude.com/docs/en/claude-directory.md#session-scratchpad-directory), where Claude keeps temporary working files. Absent when the session has no scratchpad or the temp directory is unavailable. Requires Claude Code v2.1.257 or later | | ||||
| 737 | +| `permission_mode` | Current [permission mode](https://code.claude.com/docs/en/permissions.md#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"`, or `"bypassPermissions"`. The mode labeled **Manual** arrives as `"default"`, never as `"manual"`, so scripts that match `"default"` keep working. Not all events receive this field. Check the JSON example in each [hook event](#hook-events) section | | ||||
| 738 | +| `effort` | Object whose `level` is the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) setting when the hook runs, including a skill's, subagent's, or `ultrathink` level: `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`. Present for `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, and other events with a tool-use context, on models with effort. If the model doesn't support your level, `level` is the level that ran. A level you changed can show here before it [starts](https://code.claude.com/docs/en/model-config.md#when-a-new-effort-level-starts). `$CLAUDE_EFFORT` holds the same level. | | ||||
| 739 | +| `hook_event_name` | Name of the event that fired | | ||||
| 740 | + | ||||
| 741 | +`agent_id` and `agent_type` tell your script which agent a hook fired in, such as a subagent, an [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode), or the agent you chose with `--agent`: | ||||
| 742 | + | ||||
| 743 | +| Field | Description | | ||||
| 744 | +| :- | :- | | ||||
| 745 | +| `agent_id` | Unique identifier for the subagent or in-process teammate the hook fires in. | | ||||
| 746 | +| `agent_type` | Agent name (for example, `"Explore"` or `"security-reviewer"`). Present when the session uses `--agent` or the hook fires inside a subagent. For subagents, the subagent's type takes precedence over the session's `--agent` value. See [SubagentStart](#subagentstart) for the values custom and plugin subagents report and how to write a matcher against a plugin-scoped name. | | ||||
| 747 | + | ||||
| 748 | +Only [`SessionStart`](#sessionstart) hooks can receive a `model` field, and Claude Code doesn't always include it. [`PreModelSwitch`](#premodelswitch) and [`PostModelSwitch`](#postmodelswitch) hooks receive `from_model` and `to_model` instead, so use a PostModelSwitch hook to follow the model as it changes during a session. | ||||
| 749 | + | ||||
| 750 | +There is no `$CLAUDE_MODEL` environment variable. The hook can read `$ANTHROPIC_MODEL` if you set it in your shell, but that value doesn't change when you switch models with `/model` during a session. | ||||
| 751 | + | ||||
| 752 | +A hook process inherits the parent environment, apart from the `OTEL_*` exporter variables that Claude Code [removes from every subprocess it spawns](https://code.claude.com/docs/en/monitoring-usage.md#administrator-configuration) and, when [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](https://code.claude.com/docs/en/env-vars#variables) is set to `1`, the variables it strips. In a session that [gets the HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md#check-how-developers-sign-in-and-connect), Claude Code also [removes Anthropic credentials](https://code.claude.com/docs/en/hipaa-setup.md#anthropic-credentials-in-commands-hooks-and-mcp-servers) from the hook's environment. | ||||
| 753 | + | ||||
| 754 | +For example, a `PreToolUse` hook for a Bash command receives this on stdin: | ||||
| 755 | + | ||||
| 756 | +```json theme={null} | ||||
| 757 | +{ | ||||
| 758 | + "session_id": "abc123", | ||||
| 759 | + "prompt_id": "550e8400-e29b-41d4-a716-446655440000", | ||||
| 760 | + "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl", | ||||
| 761 | + "cwd": "/home/user/my-project", | ||||
| 762 | + "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad", | ||||
| 763 | + "permission_mode": "default", | ||||
| 764 | + "hook_event_name": "PreToolUse", | ||||
| 765 | + "tool_name": "Bash", | ||||
| 766 | + "tool_input": { | ||||
| 767 | + "command": "npm test", | ||||
| 768 | + "description": "Run test suite", | ||||
| 769 | + "timeout": 120000, | ||||
| 770 | + "run_in_background": false | ||||
| 771 | + }, | ||||
| 772 | + "tool_use_id": "toolu_01ABC123..." | ||||
| 773 | +} | ||||
| 774 | +``` | ||||
| 775 | + | ||||
| 776 | +The `tool_name`, `tool_input`, and `tool_use_id` fields are event-specific. Each [hook event](#hook-events) section documents the additional fields for that event. | ||||
| 777 | + | ||||
| 778 | +### Exit code output | ||||
| 779 | + | ||||
| 780 | +When your hook's run finishes, Claude Code uses its exit code to decide whether to continue with the action that triggered it, such as a tool call or a prompt: | ||||
| 781 | + | ||||
| 782 | +* **Success**: your hook exits 0. Claude Code applies any [JSON output](#json-output) fields your hook printed, and the action goes ahead unless those fields block or deny it. [Hooks that start a background process](#hooks-that-start-a-background-process) covers the exception. | ||||
| 783 | +* **Blocking error**: your hook exits 2. On [events that can block](#exit-code-2-behavior-per-event), Claude Code stops the action. | ||||
| 784 | +* **Non-blocking error**: your hook exits with any other code, or fails in some other way, such as not starting or printing invalid JSON. The action goes ahead, except for hooks [whose failure blocks the action](#block-the-action-when-a-hook-fails), for example a hook with `onFailure` set to `"block"`. On events such as `PreToolUse`, you see a `<hook name> hook error` notice in the transcript. | ||||
| 785 | + | ||||
| 786 | +What your hook prints to stdout can change the outcome. For example, when a `PreToolUse` hook exits 1 but prints JSON that passes validation, that JSON can still decide what happens. To find your hook's outcome on an event such as `PreToolUse`, match what it printed to stdout in the first column with its exit code along the top: | ||||
| 787 | + | ||||
| 788 | +| Stdout | Exit 0 | Exit 2 | Any other exit code | | ||||
| 789 | +| :- | :- | :- | :- | | ||||
| 790 | +| JSON object that passes [schema validation](#json-output) | Success. The fields apply | Blocking error. Claude Code still reads the fields, but they can't override the block | Success. Claude Code ignores the exit code, and the fields alone decide. For hooks [whose failure blocks the action](#block-the-action-when-a-hook-fails), the run counts as a failure instead | | ||||
| 791 | +| JSON that [can't be parsed](#exit-code-0) or fails schema validation | Non-blocking error. The notice carries the parse or validation message | Blocking error. Your stderr is the reason | Non-blocking error. The notice carries the parse or validation message | | ||||
| 792 | +| [Plain text](#exit-code-0), or nothing | Success | Blocking error. Your stderr is the reason | Non-blocking error. The notice carries the first line of your stderr | | ||||
| 793 | + | ||||
| 794 | +Some events have their own rules: | ||||
| 795 | + | ||||
| 796 | +* **`WorktreeCreate`**: any non-zero exit code makes worktree creation fail, whatever your JSON says. | ||||
| 797 | +* **`WorktreeRemove`**: any non-zero exit code makes worktree removal fail if the directory still exists afterward. | ||||
| 798 | +* **`Stop`, `SubagentStop`, `TaskCompleted`, and a plugin's `UserPromptSubmit` hook**: when your hook exits 2 with nothing on stdout and its stderr says a file is missing, such as `No such file or directory`, Claude Code treats the run as a non-blocking error. | ||||
| 799 | +* **`Elicitation` and `ElicitationResult`**: Claude Code applies your `hookSpecificOutput` when your hook exits 0, and ignores it on any other exit code. | ||||
| 800 | +* **Events that discard hook output, such as `StopFailure`**: Claude Code ignores your JSON on any exit code, apart from side-effect fields like `terminalSequence`, which still fire. | ||||
| 801 | + | ||||
| 802 | +To check what exit code 2 does on your event, see [Exit code 2 behavior per event](#exit-code-2-behavior-per-event). To check which decision fields it honors, see [Decision control](#decision-control). | ||||
| 803 | + | ||||
| 804 | +#### Exit code 0 | ||||
| 805 | + | ||||
| 806 | +Exit 0 means success, and is the intended exit code when you print JSON for structured control. When your hook exits 0 but prints JSON that can't be parsed or fails [schema validation](#json-output), the action goes ahead unless the hook is one [whose failure blocks the action](#block-the-action-when-a-hook-fails). Instead of a success with your fields applied, the run is a [non-blocking error](#exit-code-output). | ||||
| 807 | + | ||||
| 808 | +To fix your output, use the parse or validation message that the `<hook name> hook error` notice carries. For a hook that isn't [async](#how-async-hooks-execute), your stdout counts as [JSON output](#json-output) only when you print one JSON object, on one line or several, with nothing around it but whitespace. Claude Code reads any other stdout as plain text or a parse failure: | ||||
| 809 | + | ||||
| 810 | +* **Output that doesn't start with `{`, or that starts with `{` and doesn't end with `}`**: plain text. A JSON array and a quoted JSON string are plain text by this rule. | ||||
| 811 | +* **Two or more lines that each parse as JSON on their own, the first starting with `{` and the last ending with `}`**: plain text when no line is a JSON output object that sets a field. When one line is, the output is a parse failure, so print that object with nothing else on stdout. | ||||
| 812 | +* **Anything else that starts with `{` and ends with `}` but isn't valid JSON**: a parse failure. | ||||
| 813 | + | ||||
| 814 | +For most events, Claude Code writes stdout to the debug log and doesn't show it in the transcript. The exceptions are `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, and `PostModelSwitch`, where Claude Code adds plain-text stdout as context that Claude can see and act on. On those events, Claude Code doesn't add stdout it failed to parse. | ||||
| 815 | + | ||||
| 816 | +Claude never sees stderr from a hook that exits 0. To read it yourself on events such as `PreToolUse`, enable [debug logging](#debug-hooks). To surface a warning to Claude from a `PostToolUse` or `PostToolUseFailure` hook, exit 2 instead so [Claude sees the stderr](#exit-code-2-behavior-per-event) even though the tool already ran. | ||||
| 817 | + | ||||
| 818 | +#### Exit code 2 | ||||
| 819 | + | ||||
| 820 | +Exit with code 2 to block the action. On [events that can block](#exit-code-2-behavior-per-event), Claude Code stops the action: a `PreToolUse` hook blocks the tool call, for example, and a `UserPromptSubmit` hook rejects the prompt. | ||||
| 821 | + | ||||
| 822 | +The message that comes with the block is your hook's stderr. If your hook also printed JSON that makes a blocking decision, Claude Code uses that decision's reason instead. | ||||
| 823 | + | ||||
| 824 | +Exit 2 blocks even when your hook prints JSON: | ||||
| 825 | + | ||||
| 826 | +* **JSON that passes schema validation**: Claude Code still reads the [JSON output](#json-output) fields, but they can't override the block. Even a `permissionDecision` of `"allow"` doesn't let the action through. On `Elicitation` and `ElicitationResult`, an exit-2 hook's `hookSpecificOutput` is ignored. | ||||
| 827 | +* **JSON that fails schema validation**: the hook still blocks. Claude Code uses your stderr as the blocking reason and records the validation failure in the debug log. | ||||
| 828 | + | ||||
| 829 | +This script blocks `rm` commands by exiting 2 and leaves every other command to the normal permission flow: | ||||
| 830 | + | ||||
| 831 | +```bash theme={null} | ||||
| 832 | +#!/bin/bash | ||||
| 833 | +# Reads JSON input from stdin, checks the command | ||||
| 834 | +input=$(cat) | ||||
| 835 | +command=$(jq -r '.tool_input.command' <<<"$input") | ||||
| 836 | + | ||||
| 837 | +if [[ "$command" == rm* ]]; then | ||||
| 838 | + echo "Blocked: rm commands are not allowed" >&2 | ||||
| 839 | + exit 2 # Blocking error: tool call is prevented | ||||
| 840 | +fi | ||||
| 841 | + | ||||
| 842 | +exit 0 # No decision: the normal permission flow applies | ||||
| 843 | +``` | ||||
| 844 | + | ||||
| 845 | +With this script registered as a `PreToolUse` hook on `Bash`, a command that starts with `rm` is blocked, and Claude receives the hook's stderr as the tool's error, prefixed with the event name, the tool name, and the hook's command: | ||||
| 846 | + | ||||
| 847 | +```text theme={null} | ||||
| 848 | +PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed | ||||
| 849 | +``` | ||||
| 850 | + | ||||
| 851 | +#### Other exit codes | ||||
| 852 | + | ||||
| 853 | +A `<hook name> hook error` notice with `Failed with non-blocking status code:` means your hook's exit code wasn't 0 or 2 and its stdout was plain text or empty. Unless the hook is one [whose failure blocks the action](#block-the-action-when-a-hook-fails), this is a [non-blocking error](#exit-code-output), so your hook didn't stop the action. To capture your hook's full stderr rather than the first line the notice shows, enable [debug logging](#debug-hooks). | ||||
| 854 | + | ||||
| 855 | +For example, when a `PreToolUse` hook on `Bash` prints `something broke` to stderr and exits 1, the `PreToolUse:Bash hook error` notice carries this line: | ||||
| 856 | + | ||||
| 857 | +```text theme={null} | ||||
| 858 | +Failed with non-blocking status code: something broke | ||||
| 859 | +``` | ||||
| 860 | + | ||||
| 861 | +If the notice carries the shell's `No such file or directory` message, as in the following line, the hook never ran, for example because its script path doesn't exist: | ||||
| 862 | + | ||||
| 863 | +```text theme={null} | ||||
| 864 | +Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory | ||||
| 865 | +``` | ||||
| 866 | + | ||||
| 867 | +If the path is wrong, correct it where the hook is configured. In shell form, when the script path doesn't exist or isn't executable, the shell exits with a code like 127 and the notice carries the interpreter's message. Unless the hook is one [whose failure blocks the action](#block-the-action-when-a-hook-fails), a hook that can't start is a non-blocking error too. | ||||
| 868 | + | ||||
| 869 | +When you set up a policy hook, watch for this notice on its first run, because a mistyped path in `settings.json` means the hook never runs. To block the action when the hook can't start, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails). | ||||
| 870 | + | ||||
| 871 | +> [!WARNING] | ||||
| 872 | +> | ||||
| 873 | +> Exit code 1 without valid JSON output is a non-blocking error unless the hook is one [whose failure blocks the action](#block-the-action-when-a-hook-fails), even though 1 is the conventional Unix failure code. If your hook is meant to enforce a policy, use `exit 2`. | ||||
| 874 | + | ||||
| 875 | +#### Timeouts | ||||
| 876 | + | ||||
| 877 | +Apart from a command hook you run with [`async: true`](#run-hooks-in-the-background), Claude Code cancels a `command`, `http`, or `mcp_tool` hook that reaches its [`timeout`](#common-fields), discarding the hook's output, so on most events a timed-out hook renders no decision. On [`PreModelSwitch`](#premodelswitch), a hook canceled at its timeout blocks the model switch. | ||||
| 878 | + | ||||
| 879 | +On `PreToolUse`, a timed-out `command`, `http`, or `mcp_tool` hook doesn't block the tool call, except for hooks [whose failure blocks the action](#block-the-action-when-a-hook-fails). The call continues through the normal [permission flow](https://code.claude.com/docs/en/permissions.md), so don't count on a stalled hook to act as a gate. To block the call when a `command` or `http` hook times out, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails). An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md) that exceeds its timeout [blocks the tool call](#pretooluse). | ||||
| 880 | + | ||||
| 881 | +#### Hooks that start a background process | ||||
| 882 | + | ||||
| 883 | +If your command hook makes its decision in a background process and exits, a deny that process prints after Claude Code has stopped reading doesn't block the tool call. For a hook that isn't [async](#run-hooks-in-the-background), Claude Code finishes reading the hook's output shortly after the hook's own process exits. | ||||
| 884 | + | ||||
| 885 | +Print the decision before you start a background process, and redirect that process's stdout and stderr. If your script prints an allow, then starts a background process without redirecting that process's stdout and stderr, Claude Code blocks the tool call. The hook error includes `refusing to honor the suspect capture`. | ||||
| 886 | + | ||||
| 887 | +This `PreToolUse` hook script prints the decision with `policy-check.sh`, then uploads metrics in the background: | ||||
| 888 | + | ||||
| 889 | +```bash theme={null} | ||||
| 890 | +#!/bin/bash | ||||
| 891 | +"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $? | ||||
| 892 | +"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 & | ||||
| 893 | +``` | ||||
| 894 | + | ||||
| 895 | +The rest of the script does this: | ||||
| 896 | + | ||||
| 897 | +* **`|| exit $?`**: makes the check's exit code the hook's own, so a check that exits 2 to deny still blocks. Otherwise the hook exits with the last line's code, which is 0. | ||||
| 898 | +* **`>/dev/null 2>&1 &`**: runs `upload-metrics.sh` in the background with its output redirected, so it doesn't keep the hook's output open. | ||||
| 899 | + | ||||
| 900 | +To test the script, make `policy-check.sh` exit 2, then trigger a tool call that the hook matches. The tool call is blocked. | ||||
| 901 | + | ||||
| 902 | +#### Block the action when a hook fails | ||||
| 903 | + | ||||
| 904 | +On most events, when a hook fails or times out, Claude Code still carries out the action. A policy hook with a wrong path or a crashing script then lets everything through. To block the action instead, set `"onFailure": "block"` on a `command` or `http` hook. Requires Claude Code v2.1.295 or later. | ||||
| 905 | + | ||||
| 906 | +> [!NOTE] | ||||
| 907 | +> | ||||
| 908 | +> On Windows without Git Bash, a shell-form `PreToolUse` or `PermissionRequest` command hook that fails with `onFailure` unset can instead [block the tool call](#failed-hooks-on-windows-without-git-bash). | ||||
| 909 | + | ||||
| 910 | +This `PreToolUse` hook in `.claude/settings.json` runs a project script before each Bash command, and blocks the command if the script fails: | ||||
| 911 | + | ||||
| 912 | +```json theme={null} | ||||
| 913 | +{ | ||||
| 914 | + "hooks": { | ||||
| 915 | + "PreToolUse": [ | ||||
| 916 | + { | ||||
| 917 | + "matcher": "Bash", | ||||
| 918 | + "hooks": [ | ||||
| 919 | + { | ||||
| 920 | + "type": "command", | ||||
| 921 | + "command": "node", | ||||
| 922 | + "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"], | ||||
| 923 | + "onFailure": "block" | ||||
| 924 | + } | ||||
| 925 | + ] | ||||
| 926 | + } | ||||
| 927 | + ] | ||||
| 928 | + } | ||||
| 929 | +} | ||||
| 930 | +``` | ||||
| 931 | + | ||||
| 932 | +To test it, leave `check-command.js` missing and ask Claude to run a Bash command such as `ls`. Claude Code blocks the call, and the error includes `failed; blocking because onFailure is "block"` followed by node's own error output, trimmed here to one line: | ||||
| 933 | + | ||||
| 934 | +```text theme={null} | ||||
| 935 | +PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block" | ||||
| 936 | +Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js' | ||||
| 937 | +``` | ||||
| 938 | + | ||||
| 939 | +After a timeout, the message says `timed out` instead of `failed`. Without `onFailure` set, the same missing script is a non-blocking error and `ls` runs. | ||||
| 940 | + | ||||
| 941 | +Each of these counts as a failure: | ||||
| 942 | + | ||||
| 943 | +* **Can't start**: a command hook fails to start, for example because the script or executable doesn't exist | ||||
| 944 | +* **Exit code other than 0 or 2**: counts for a command hook even if it printed JSON that allows the action, such as `permissionDecision: "allow"`. To return a JSON decision, exit 0 | ||||
| 945 | +* **HTTP error**: an HTTP hook's connection fails, or the response status isn't 2xx | ||||
| 946 | +* **Timeout**: the hook reaches its [`timeout`](#common-fields) | ||||
| 947 | +* **Invalid output**: the JSON output [can't be parsed](#exit-code-0) or fails [schema validation](#json-output). For an HTTP hook, a 2xx body that is neither empty nor a JSON object also counts. Plain-text stdout from a command hook isn't a failure | ||||
| 948 | + | ||||
| 949 | +With `"block"` set, a failure does what [exit code 2 does on that event](#exit-code-2-behavior-per-event), except on `PermissionRequest`, where it denies the request. For example, a `PreToolUse` failure blocks the tool call and a `UserPromptSubmit` failure blocks the prompt. | ||||
| 950 | + | ||||
| 951 | +The field has no effect on these hooks: | ||||
| 952 | + | ||||
| 953 | +* **`Stop`, `SubagentStop`, `TaskCompleted`, and `TeammateIdle` hooks**: exit code 2 on these events sends Claude back to keep working, and Claude can't repair a hook that won't run | ||||
| 954 | +* **Background command hooks**: command hooks that set [`async` or `asyncRewake`](#run-hooks-in-the-background) | ||||
| 955 | + | ||||
| 956 | +#### Failed hooks on Windows without Git Bash | ||||
| 957 | + | ||||
| 958 | +If the error for a blocked tool call includes this text, a `PreToolUse` or `PermissionRequest` command hook failed or timed out and blocked the call: | ||||
| 959 | + | ||||
| 960 | +```text theme={null} | ||||
| 961 | +blocking because Git Bash wasn't found, so only exit code 0 or 2 counts as this hook's verdict. | ||||
| 962 | +``` | ||||
| 963 | + | ||||
| 964 | +If the error also says `PowerShell started no program`, start with [the fixes for a `command` that is only quoted strings](#powershell-started-no-program), which PowerShell prints instead of running. | ||||
| 965 | + | ||||
| 966 | +Without Git Bash, any exit code other than 0 or 2 from that hook counts as a [failure](#block-the-action-when-a-hook-fails), even when it prints JSON that doesn't deny the call. To find out why the hook failed, check the [debug log](#debug-hooks). Then pick the fix that matches your hook: | ||||
| 967 | + | ||||
| 968 | +* **The call should go ahead when the hook fails**: add [`"onFailure": "continue"`](#block-the-action-when-a-hook-fails) to the hook | ||||
| 969 | +* **The hook exits 1 to warn but must block when it crashes**: with `"onFailure": "continue"`, the call goes ahead on exit code 1, warning or crash alike. Add `"onFailure": "block"` instead, and have the script exit 0 where it warns, so those calls go ahead. To still show the warning on `PreToolUse`, print it to stdout as the [`systemMessage`](#json-output) field of one JSON object. | ||||
| 970 | +* **The hook is written for Bash**: without Git Bash, a [shell-form](#exec-form-and-shell-form) hook with no `shell` set runs in PowerShell, where it can fail. Install [Git for Windows](https://git-scm.com/downloads/win), or set [`CLAUDE_CODE_GIT_BASH_PATH`](https://code.claude.com/docs/en/env-vars) if Git Bash is installed where Claude Code doesn't find it. Then start a new session. | ||||
| 971 | +* **The hook runs one `.exe`, not a `.cmd` or `.bat` file**: put the program in `command` and its arguments in `args` to use exec form, and add `"onFailure": "block"`. Claude Code then starts the program with no shell. Without `"onFailure": "block"`, the call can go ahead when the program fails, is missing, or times out | ||||
| 972 | +* **A PowerShell guard hook that must block on failure**: with `onFailure` unset, it stops doing so once Git for Windows is installed and Claude Code finds Git Bash. Add `"onFailure": "block"` so a failure or a timeout blocks the call with or without Git Bash. Also set `"shell": "powershell"` so the hook keeps running in PowerShell from then on instead of in Git Bash | ||||
| 973 | + | ||||
| 974 | +Before v2.1.309, the message read `blocking because Git Bash wasn't found and this hook doesn't set "shell" to "powershell", so only exit code 0 or 2 counts as its verdict.` | ||||
| 975 | + | ||||
| 976 | +#### PowerShell started no program | ||||
| 977 | + | ||||
| 978 | +A hook with this error ran in PowerShell, which prints a `command` that is only quoted strings, such as `"command": "\"C:\\Tools\\guard.exe\""`, instead of running it. | ||||
| 979 | + | ||||
| 980 | +* **To print text, such as JSON**: set `"shell": "powershell"`, and the hook exits 0 | ||||
| 981 | +* **To run a `.ps1`, `.cmd`, or `.bat` file, or a `.exe` whose path has a variable**: set `"shell": "powershell"` and put `&` before the quoted path. Leave `$HOME` as written, and spell environment variables as the [`check.ps1` example](#reference-scripts-by-path-in-powershell-hooks) spells `$env:CLAUDE_PROJECT_DIR` | ||||
| 982 | +* **To run one `.exe` at a path without `$`**: remove the inner quotes from `command`, then apply the [fix for a hook that runs one `.exe`](#failed-hooks-on-windows-without-git-bash), writing `"args": []` if the program takes no arguments | ||||
| 983 | +* **To run a script written for Bash**: apply the [fix for a hook written for Bash](#failed-hooks-on-windows-without-git-bash) | ||||
| 984 | + | ||||
| 985 | +#### Exit code 2 behavior per event | ||||
| 986 | + | ||||
| 987 | +Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented. | ||||
| 988 | + | ||||
| 989 | +| Hook event | Can block? | What happens on exit 2 | | ||||
| 990 | +| :- | :- | :- | | ||||
| 991 | +| `PreToolUse` | Yes | Blocks the tool call | | ||||
| 992 | +| `PermissionRequest` | No | Exit code 2 isn't honored for this event and the permission flow proceeds unchanged. Deny through the [`decision` object](#permissionrequest-decision-control) instead | | ||||
| 993 | +| `UserPromptSubmit` | Yes | Blocks the prompt, so it never reaches Claude. See [What a blocked prompt leaves behind](#what-a-blocked-prompt-leaves-behind) | | ||||
| 994 | +| `UserPromptExpansion` | Yes | Blocks the expansion | | ||||
| 995 | +| `Stop` | Yes | Prevents Claude from stopping, continues the conversation | | ||||
| 996 | +| `SubagentStop` | Yes | Prevents the subagent from stopping | | ||||
| 997 | +| `TeammateIdle` | Yes | Prevents the teammate from going idle, so it continues working | | ||||
| 998 | +| `TaskCreated` | Yes | Rolls back the task creation | | ||||
| 999 | +| `TaskCompleted` | Yes | Prevents the task from being marked as completed | | ||||
| 1000 | +| `ConfigChange` | Yes | Blocks the configuration change from taking effect (except `policy_settings`) | | ||||
| 1001 | +| `StopFailure` | No | Output and exit code are ignored, except `terminalSequence` | | ||||
| 1002 | +| `PostToolUse` | No | Shows stderr to Claude; the tool already ran | | ||||
| 1003 | +| `PostToolUseFailure` | No | Shows stderr to Claude; the tool already failed | | ||||
| 1004 | +| `PostToolBatch` | Yes | Stops the agentic loop before the next model call | | ||||
| 1005 | +| `PermissionDenied` | No | Exit code and stderr are ignored because the denial already occurred. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry; Claude Code ignores `retry: true` for [no-verdict denials](#permissiondenied-decision-control) | | ||||
| 1006 | +| `Notification` | No | Exit code and stderr are ignored | | ||||
| 1007 | +| `SubagentStart` | No | Shows stderr to user only | | ||||
| 1008 | +| `SessionStart` | No | Shows stderr to user only | | ||||
| 1009 | +| `Setup` | No | Exit code and stderr are ignored | | ||||
| 1010 | +| `SessionEnd` | No | Shows stderr to user only | | ||||
| 1011 | +| `CwdChanged` | No | Shows stderr to user only | | ||||
| 1012 | +| `DirectoryAdded` | No | Stderr goes to the debug log; the directory is already added | | ||||
| 1013 | +| `FileChanged` | No | Shows stderr to user only | | ||||
| 1014 | +| `PreCompact` | Yes | Blocks compaction | | ||||
| 1015 | +| `PostCompact` | No | Shows stderr to user only | | ||||
| 1016 | +| `PreModelSwitch` | Yes | Blocks the model switch and shows stderr to the user | | ||||
| 1017 | +| `PostModelSwitch` | No | Shows stderr to user only; the model already switched | | ||||
| 1018 | +| `Elicitation` | Yes | Declines the request, and no dialog appears | | ||||
| 1019 | +| `ElicitationResult` | Yes | Blocks the response (action becomes decline) | | ||||
| 1020 | +| `WorktreeCreate` | Yes | Any non-zero exit code causes worktree creation to fail | | ||||
| 1021 | +| `WorktreeRemove` | Yes | Any non-zero exit code causes worktree removal to fail if the directory still exists afterward. See [WorktreeRemove](#worktreeremove) for what happens to the directory | | ||||
| 1022 | +| `InstructionsLoaded` | No | Exit code is ignored | | ||||
| 1023 | +| `MessageDisplay` | No | The original text is displayed | | ||||
| 1024 | + | ||||
| 1025 | +For `SessionStart`, `SubagentStart`, and `PostModelSwitch`, Claude Code renders the exit code 2 stderr in the transcript as a `<hook name> hook error` notice, the same way it renders a [non-blocking error](#exit-code-output). Claude doesn't see it, and the session or subagent proceeds. For `SubagentStart`, the notice appears in the subagent's own transcript, not in the parent conversation. | ||||
| 1026 | + | ||||
| 1027 | +### HTTP response handling | ||||
| 1028 | + | ||||
| 1029 | +HTTP hooks use HTTP status codes and response bodies instead of exit codes and stdout. To block the action when the request fails or returns a non-2xx status, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails). To block a tool call or deny a permission, return a 2xx response with a JSON body containing the appropriate [decision fields](#decision-control). | ||||
| 1030 | + | ||||
| 1031 | +After a [non-blocking error](#exit-code-output), the action goes ahead unless the hook is one [whose failure blocks the action](#block-the-action-when-a-hook-fails). Except on events with their own failure contract in the [per-event table](#exit-code-2-behavior-per-event), such as `WorktreeCreate`, you get these results for each response or failure: | ||||
| 1032 | + | ||||
| 1033 | +* **2xx with an empty body**: success, equivalent to exit code 0 with no output | ||||
| 1034 | +* **2xx with a JSON object body**: parsed using the same [JSON output](#json-output) schema as command hooks. A body that fails schema validation is a non-blocking error | ||||
| 1035 | +* **2xx with any other body, such as plain text**: non-blocking error, handled the same as a non-2xx status. Claude Code doesn't add the text to Claude's context | ||||
| 1036 | +* **Non-2xx status**: non-blocking error | ||||
| 1037 | +* **Connection failure**: non-blocking error | ||||
| 1038 | +* **Timeout**: the hook is canceled, as described under [Timeouts](#timeouts) | ||||
| 1039 | + | ||||
| 1040 | +### JSON output | ||||
| 1041 | + | ||||
| 1042 | +Exit codes only let you block or stay silent, but JSON output gives you finer-grained control. Instead of exiting with code 2 to block, exit 0 and print a JSON object to stdout. Claude Code reads specific fields from that JSON to control behavior, including [decision control](#decision-control) for blocking, allowing, or escalating to the user. | ||||
| 1043 | + | ||||
| 1044 | +> [!NOTE] | ||||
| 1045 | +> | ||||
| 1046 | +> Choose one approach per hook: either use exit codes alone for signaling, or exit 0 and print JSON for structured control. If you mix them, exit 2 keeps its [blocking effect](#exit-code-2-behavior-per-event), and Claude Code still reads the JSON fields, with the one elicitation exception noted under [Exit code 2](#exit-code-2). | ||||
| 1047 | + | ||||
| 1048 | +Print nothing but the JSON object to stdout. For a hook that isn't [async](#how-async-hooks-execute), other text there, such as a line your shell profile echoes at startup, keeps Claude Code from reading the object as JSON, and [Hook JSON has no effect](https://code.claude.com/docs/en/hooks-guide.md#hook-json-has-no-effect) shows how to find and silence that text. | ||||
| 1049 | + | ||||
| 1050 | +A hook's `additionalContext`, `systemMessage`, and `initialUserMessage` strings, and its plain stdout, are capped at 10,000 characters: | ||||
| 1051 | + | ||||
| 1052 | +* **Scope**: Claude Code measures each string on its own, even when several hooks run for the same event. For JSON output, each field is measured separately; plain stdout is measured whole. | ||||
| 1053 | +* **Over the limit**: Claude Code saves the output to a file in the session directory and replaces it with the file path and a preview of up to the first 2,000 characters. A large valid Bash result is handled the same way, described under [Output limits](https://code.claude.com/docs/en/tools-reference.md#output-limits). Unlike that Bash ceiling, this cap has no setting or environment variable to raise it. | ||||
| 1054 | +* **Reading the file**: Claude Code doesn't ask Claude to read the file, so keep anything Claude must always see within the cap. | ||||
| 1055 | + | ||||
| 1056 | +The JSON object supports three kinds of fields: | ||||
| 1057 | + | ||||
| 1058 | +* **Universal fields** like `continue` are listed in the table below. Every event accepts them, but some events discard them or deliver `systemMessage` somewhere other than the transcript. Each event's section says so. `terminalSequence` works on those events too, with the exceptions listed under [Emit terminal notifications](#emit-terminal-notifications). | ||||
| 1059 | +* **Top-level `decision` and `reason`** are used by some events to block or provide feedback. | ||||
| 1060 | +* **`hookSpecificOutput`** is a nested object for events that need richer control. It requires a `hookEventName` field set to the event name. | ||||
| 1061 | + | ||||
| 1062 | +| Field | Default | Description | | ||||
| 1063 | +| :- | :- | :- | | ||||
| 1064 | +| `continue` | `true` | If `false`, Claude stops processing entirely after the hook runs. Takes precedence over any event-specific decision fields | | ||||
| 1065 | +| `stopReason` | none | Message shown to the user when `continue` is `false`. It stays in the conversation, so Claude sees it if the conversation continues | | ||||
| 1066 | +| `suppressOutput` | `false` | Has no effect: Claude Code accepts the field but doesn't act on it. A successful hook's stdout is never shown in the transcript and is recorded in the debug log | | ||||
| 1067 | +| `systemMessage` | none | Warning message shown to the user. In [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) and [`--output-format stream-json`](https://code.claude.com/docs/en/headless) output, it can arrive as an [`SDKInformationalMessage`](https://code.claude.com/docs/en/agent-sdk/typescript#sdkinformationalmessage) | | ||||
| 1068 | +| `terminalSequence` | none | A terminal escape sequence for Claude Code to emit on your behalf, such as a desktop notification, window title, or bell. Restricted to OSC `0`/`1`/`2`/`9`/`99`/`777` and BEL. If the value contains anything outside the allowlist, the field is ignored. Use this instead of writing to `/dev/tty`, which is unavailable to hooks | | ||||
| 1069 | + | ||||
| 1070 | +To stop Claude entirely: | ||||
| 1071 | + | ||||
| 1072 | +```json theme={null} | ||||
| 1073 | +{ "continue": false, "stopReason": "Build failed, fix errors before continuing" } | ||||
| 1074 | +``` | ||||
| 1075 | + | ||||
| 1076 | +For `PreToolUse` and `PostToolUse` hooks, the stop applies even when the tool call fails or completes while Claude is still streaming a response. | ||||
| 1077 | + | ||||
| 1078 | +#### Emit terminal notifications | ||||
| 1079 | + | ||||
| 1080 | +Hooks run without a controlling terminal, so writing escape sequences directly to `/dev/tty` fails. Instead, return the escape sequence in the `terminalSequence` field and Claude Code emits it for you through its own terminal write path. This is race-free, works inside tmux and GNU screen, and works on Windows where there is no `/dev/tty`. | ||||
| 1081 | + | ||||
| 1082 | +The field accepts a string of one or more allowlisted escape sequences: | ||||
| 1083 | + | ||||
| 1084 | +* OSC `0`, `1`, `2`: window and icon titles | ||||
| 1085 | +* OSC `9`: iTerm2, ConEmu, Windows Terminal, and WezTerm notifications, including `9;4` taskbar progress | ||||
| 1086 | +* OSC `99`: Kitty notifications | ||||
| 1087 | +* OSC `777`: urxvt, Ghostty, and Warp notifications | ||||
| 1088 | +* Bare BEL | ||||
| 1089 | + | ||||
| 1090 | +Sequences may be terminated with BEL or with ST. Anything outside the allowlist, including CSI cursor and color sequences, OSC palette sequences, OSC 8 hyperlinks, OSC 52 clipboard writes, and OSC 1337, is rejected and the field is ignored. | ||||
| 1091 | + | ||||
| 1092 | +Claude Code writes the sequence itself when it processes your hook's output, so the field works on events that discard `systemMessage` and `continue`, such as `Notification` and `StopFailure`. It has two limits: | ||||
| 1093 | + | ||||
| 1094 | +* Claude Code writes the sequence only in an interactive session, and only while its interface is on screen. In non-interactive mode with the `-p` flag and in the Agent SDK, it ignores the field. | ||||
| 1095 | +* A `WorktreeCreate` command hook can't return JSON, because Claude Code reads its stdout as the worktree path. An HTTP `WorktreeCreate` hook returns JSON and can include the field. | ||||
| 1096 | + | ||||
| 1097 | +The example below fires a desktop notification from a `Notification` hook. The escape sequence is built with `printf` octal escapes so the control bytes never appear on the shell command line, and `jq -n --arg` builds the JSON output so quotes, backslashes, and newlines in the notification message are escaped correctly: | ||||
| 1098 | + | ||||
| 1099 | +```bash theme={null} | ||||
| 1100 | +#!/bin/bash | ||||
| 1101 | +# Notification hook: ping the desktop when Claude Code needs attention. | ||||
| 1102 | +input=$(cat) | ||||
| 1103 | +title="Claude Code" | ||||
| 1104 | +body=$(jq -r '.message // "Needs your attention"' <<<"$input") | ||||
| 1105 | +seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body") | ||||
| 1106 | +jq -nc --arg seq "$seq" '{terminalSequence: $seq}' | ||||
| 1107 | +``` | ||||
| 1108 | + | ||||
| 1109 | +The `{ "terminalSequence": "..." }` shape is the same from any shell or language. | ||||
| 1110 | + | ||||
| 1111 | +#### Add context for Claude | ||||
| 1112 | + | ||||
| 1113 | +The `additionalContext` field passes a string from your hook into Claude's context window. Claude Code wraps the string in a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder) and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it doesn't appear as a chat message in the interface. | ||||
| 1114 | + | ||||
| 1115 | +Return `additionalContext` inside `hookSpecificOutput` alongside the event name: | ||||
| 1116 | + | ||||
| 1117 | +```json theme={null} | ||||
| 1118 | +{ | ||||
| 1119 | + "hookSpecificOutput": { | ||||
| 1120 | + "hookEventName": "PostToolUse", | ||||
| 1121 | + "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead." | ||||
| 1122 | + } | ||||
| 1123 | +} | ||||
| 1124 | +``` | ||||
| 1125 | + | ||||
| 1126 | +Where the reminder appears depends on the event: | ||||
| 1127 | + | ||||
| 1128 | +* [SessionStart](#sessionstart) and [SubagentStart](#subagentstart): at the start of the conversation, before the first prompt | ||||
| 1129 | +* [UserPromptSubmit](#userpromptsubmit) and [UserPromptExpansion](#userpromptexpansion): alongside the submitted prompt | ||||
| 1130 | +* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure), and [PostToolBatch](#posttoolbatch): next to the tool result | ||||
| 1131 | +* [Stop](#stop) and [SubagentStop](#subagentstop): at the end of the turn. The conversation continues so Claude can act on the feedback. See [Stop decision control](#stop-decision-control) | ||||
| 1132 | +* [PostModelSwitch](#postmodelswitch): with the next request after the switch. See [PostModelSwitch decision control](#postmodelswitch-decision-control) for timing | ||||
| 1133 | + | ||||
| 1134 | +When several hooks return `additionalContext` for the same event, Claude receives all of the values. | ||||
| 1135 | + | ||||
| 1136 | +If your string contains a `<system-reminder>` or `</system-reminder>` tag, Claude receives the string with that tag's `<` replaced by `<`. | ||||
| 1137 | + | ||||
| 1138 | +If a value exceeds 10,000 characters, Claude Code writes the text to a file in the session directory and passes Claude the file path with a preview of up to the first 2,000 characters instead. Claude can read the file, but Claude Code doesn't ask it to. | ||||
| 1139 | + | ||||
| 1140 | +Use `additionalContext` for information Claude should know about the current state of your environment or the operation that just ran: | ||||
| 1141 | + | ||||
| 1142 | +* **Environment state**: the current branch, deployment target, or active feature flags | ||||
| 1143 | +* **Conditional project rules**: which test command applies to the file just edited, which directories are read-only in this worktree | ||||
| 1144 | +* **External data**: open issues assigned to you, recent CI results, content fetched from an internal service | ||||
| 1145 | + | ||||
| 1146 | +For instructions that never change, prefer [CLAUDE.md](https://code.claude.com/docs/en/memory.md). It loads without running a script and is the standard place for static project conventions. | ||||
| 1147 | + | ||||
| 1148 | +Write the text as factual statements rather than imperative system instructions. Phrasing such as "The deployment target is production" or "This repo uses `bun test`" reads as project information. Text framed as out-of-band system commands can trigger Claude's prompt-injection defenses, which causes Claude to surface the text to you instead of treating it as context. | ||||
| 1149 | + | ||||
| 1150 | +Claude Code saves the injected text in the session transcript. For mid-session events like `PostToolUse` or `UserPromptSubmit`, when you resume with `--continue` or `--resume`, Claude Code replays the saved text rather than re-running the hook for past turns, so values like timestamps or commit SHAs become stale. `SessionStart` hooks run again on resume with `source` set to `"resume"`, or `"fork"` if you added `--fork-session`, so they can refresh their context. | ||||
| 1151 | + | ||||
| 1152 | +#### Decision control | ||||
| 1153 | + | ||||
| 1154 | +Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook: | ||||
| 1155 | + | ||||
| 1156 | +| Events | Decision pattern | Key fields | | ||||
| 1157 | +| :- | :- | :- | | ||||
| 1158 | +| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | Top-level `decision` | `decision: "block"`, `reason`. Stop and SubagentStop also accept `hookSpecificOutput.additionalContext` for [non-error feedback that continues the conversation](#stop-decision-control) | | ||||
| 1159 | +| TeammateIdle, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior; [TaskCompleted ignores it when the `TaskUpdate` tool triggered the event](#taskcompleted-decision-control) | | ||||
| 1160 | +| TaskCreated | Exit code or top-level `decision` | Exit code 2 or `decision: "block"` [cancels the task](#taskcreated-decision-control) and returns the message to Claude. `continue: false` is ignored | | ||||
| 1161 | +| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` | | ||||
| 1162 | +| PreModelSwitch | `hookSpecificOutput` or top-level `decision` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason`. `decision: "block"` also [cancels the switch](#premodelswitch-decision-control) | | ||||
| 1163 | +| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) | | ||||
| 1164 | +| PermissionDenied | `hookSpecificOutput` | `retry: true` tells the model it may retry the denied tool call; Claude Code ignores it for [no-verdict denials](#permissiondenied-decision-control) | | ||||
| 1165 | +| WorktreeCreate | path return | Command hook prints path on stdout; HTTP hook returns `hookSpecificOutput.worktreePath`. Hook failure or missing path fails creation | | ||||
| 1166 | +| WorktreeRemove | Exit code | Any non-zero exit code makes the removal fail if the directory still exists afterward. JSON output is discarded | | ||||
| 1167 | +| Elicitation, ElicitationResult | `hookSpecificOutput` or top-level `decision` | `action` (accept/decline/cancel), `content` (form field values). `decision: "block"` also [declines](#other-ways-to-decline-an-elicitation) | | ||||
| 1168 | +| MessageDisplay | `hookSpecificOutput` | `displayContent` replaces the displayed text on screen. Display-only: the transcript and what Claude sees keep the original | | ||||
| 1169 | +| SessionStart, SubagentStart, PostModelSwitch | Context only | `hookSpecificOutput.additionalContext` adds context for Claude. SessionStart also accepts [`initialUserMessage`, `watchPaths`, `sessionTitle`, and `reloadSkills`](#sessionstart-decision-control). No blocking or decision control | | ||||
| 1170 | +| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | None | No decision control. Used for side effects like logging or cleanup | | ||||
| 1171 | + | ||||
| 1172 | +A few events can also rewrite content rather than only allow or block it: | ||||
| 1173 | + | ||||
| 1174 | +* `PreToolUse`: `updatedInput` directly under `hookSpecificOutput` replaces a tool's arguments before it runs. See [PreToolUse decision control](#pretooluse-decision-control) | ||||
| 1175 | +* `PermissionRequest`: `updatedInput` inside the `decision` object. See [PermissionRequest decision control](#permissionrequest-decision-control) | ||||
| 1176 | +* `PostToolUse`: `updatedToolOutput` replaces the tool's result. See [PostToolUse decision control](#posttooluse-decision-control) | ||||
| 1177 | +* `UserPromptSubmit`: can't replace the prompt; it only injects `additionalContext` alongside it | ||||
| 1178 | + | ||||
| 1179 | +For redaction or transformation use cases, intercept at `PreToolUse` for outbound tool inputs and `PostToolUse` for inbound tool results. | ||||
| 1180 | + | ||||
| 1181 | +Here are examples of each pattern in action: | ||||
| 1182 | + | ||||
| 1183 | +**Top-level decision** | ||||
| 1184 | + | ||||
| 1185 | +The only value for `decision` is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all: | ||||
| 1186 | + | ||||
| 1187 | +```json theme={null} | ||||
| 1188 | +{ | ||||
| 1189 | + "decision": "block", | ||||
| 1190 | + "reason": "Test suite must pass before proceeding" | ||||
| 1191 | +} | ||||
| 1192 | +``` | ||||
| 1193 | + | ||||
| 1194 | +**PreToolUse** | ||||
| 1195 | + | ||||
| 1196 | +Uses `hookSpecificOutput` for richer control: allow, deny, or escalate to the user. You can also modify tool input before it runs or inject additional context for Claude. See [PreToolUse decision control](#pretooluse-decision-control) for the full set of options. | ||||
| 1197 | + | ||||
| 1198 | +```json theme={null} | ||||
| 1199 | +{ | ||||
| 1200 | + "hookSpecificOutput": { | ||||
| 1201 | + "hookEventName": "PreToolUse", | ||||
| 1202 | + "permissionDecision": "deny", | ||||
| 1203 | + "permissionDecisionReason": "Database writes are not allowed" | ||||
| 1204 | + } | ||||
| 1205 | +} | ||||
| 1206 | +``` | ||||
| 1207 | + | ||||
| 1208 | +**PermissionRequest** | ||||
| 1209 | + | ||||
| 1210 | +Uses `hookSpecificOutput` to allow or deny a permission request on behalf of the user. When allowing, you can also modify the tool's input or apply permission rules so the user isn't prompted again. See [PermissionRequest decision control](#permissionrequest-decision-control) for the full set of options. | ||||
| 1211 | + | ||||
| 1212 | +```json theme={null} | ||||
| 1213 | +{ | ||||
| 1214 | + "hookSpecificOutput": { | ||||
| 1215 | + "hookEventName": "PermissionRequest", | ||||
| 1216 | + "decision": { | ||||
| 1217 | + "behavior": "allow", | ||||
| 1218 | + "updatedInput": { | ||||
| 1219 | + "command": "npm run lint" | ||||
| 1220 | + } | ||||
| 1221 | + } | ||||
| 1222 | + } | ||||
| 1223 | +} | ||||
| 1224 | +``` | ||||
| 1225 | + | ||||
| 1226 | +For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see [What you can automate](https://code.claude.com/docs/en/hooks-guide.md#what-you-can-automate) in the guide and the [Bash command validator reference implementation](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py). | ||||
| 1227 | + | ||||
| 1228 | +## Hook events | ||||
| 1229 | + | ||||
| 1230 | +Each event corresponds to a point in Claude Code's lifecycle where hooks can run. The sections below are ordered to match the lifecycle: from session setup through the agentic loop to session end. Each section describes when the event fires, what matchers it supports, the JSON input it receives, and how to control behavior through output. | ||||
| 1231 | + | ||||
| 1232 | +### SessionStart | ||||
| 1233 | + | ||||
| 1234 | +Runs when Claude Code starts a new session or resumes an existing session. Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables. For static context that doesn't require a script, use [CLAUDE.md](https://code.claude.com/docs/en/memory.md) instead. | ||||
| 1235 | + | ||||
| 1236 | +SessionStart runs on every session, so keep these hooks fast. Only `type: "command"` and `type: "mcp_tool"` hooks are supported. See [MCP tool hook fields](#mcp-tool-hook-fields) for when `mcp_tool` hooks run. | ||||
| 1237 | + | ||||
| 1238 | +The matcher value corresponds to how the session was initiated: | ||||
| 1239 | + | ||||
| 1240 | +| Matcher | When it fires | | ||||
| 1241 | +| :- | :- | | ||||
| 1242 | +| `startup` | New session | | ||||
| 1243 | +| `resume` | `--resume`, `--continue`, or `/resume` | | ||||
| 1244 | +| `clear` | `/clear` | | ||||
| 1245 | +| `compact` | Auto or manual compaction | | ||||
| 1246 | +| `fork` | A new session forked from an existing one: `--fork-session` with `--resume` or `--continue`, the `/fork` background copy, `/branch`, or a conversation you [move to the background](https://code.claude.com/docs/en/agent-view.md#from-inside-a-session) | | ||||
| 1247 | + | ||||
| 1248 | +When you start an interactive session, resume a conversation at launch with `--continue` or `--resume`, or run `/clear`, SessionStart hooks run in the background. You can type right away, and a conversation you resumed appears without waiting for the hooks. Claude's first response still waits for the hooks to finish, so their context reaches Claude. | ||||
| 1249 | + | ||||
| 1250 | +When you switch conversations with `/resume` inside a session, the switch waits for the hooks to finish instead. If you run `/clear` or switch to another conversation while background hooks are still running, nothing they return applies to the session. | ||||
| 1251 | + | ||||
| 1252 | +The same wait applies at launch, including a resumed session: a prompt you send while SessionStart hooks are still running doesn't reach Claude until they finish. | ||||
| 1253 | + | ||||
| 1254 | +During either wait, press `Esc` to take the prompt back into the input without sending it. The hooks keep running. | ||||
| 1255 | + | ||||
| 1256 | +#### SessionStart input | ||||
| 1257 | + | ||||
| 1258 | +In addition to the [common input fields](#common-input-fields), SessionStart hooks receive `source` and optionally `model`, `agent_type`, and `session_title`: | ||||
| 1259 | + | ||||
| 1260 | +| Field | Description | | ||||
| 1261 | +| :- | :- | | ||||
| 1262 | +| `source` | How the session started: `"startup"` for new sessions, `"resume"` for resumed sessions, `"clear"` after `/clear`, `"compact"` after compaction, or `"fork"` for a new session forked from an existing one | | ||||
| 1263 | +| `model` | The active model identifier. It can be omitted, for example after `/clear` or when a session is restored through conversation recovery, so check for the field before reading it | | ||||
| 1264 | +| `agent_type` | The agent name, present when you start Claude Code with `claude --agent <name>` | | ||||
| 1265 | +| `session_title` | The session's custom title, present when one is set, for example with `--name`, `/rename`, a hook's `sessionTitle` output, or the Agent SDK's `renameSession()`. A hook that emits `sessionTitle` can check this field first to avoid overwriting an existing custom title | | ||||
| 1266 | + | ||||
| 1267 | +A session you haven't named can still have a [generated title](https://code.claude.com/docs/en/sessions.md#name-your-sessions). That title isn't a custom title and doesn't appear in `session_title`. | ||||
| 1268 | + | ||||
| 1269 | +When `source` is `"resume"` or `"fork"` and the transcript contains at least one response from Claude, SessionStart hooks also receive the four fields below. Your hook can use them to report what resuming a stale conversation costs before the first request, for example in a [`systemMessage`](#json-output). These fields require Claude Code v2.1.251 or later. | ||||
| 1270 | + | ||||
| 1271 | +| Field | Description | | ||||
| 1272 | +| :- | :- | | ||||
| 1273 | +| `seconds_since_last_response` | Wall-clock seconds since the last response in the resumed transcript | | ||||
| 1274 | +| `context_tokens` | Tokens the first request of the resumed session re-sends as its prompt | | ||||
| 1275 | +| `prompt_cache_likely_expired` | `true` when the last response is older than the session's [prompt cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime) or a later compaction replaced the cached conversation | | ||||
| 1276 | +| `estimated_cache_write_usd` | Estimated cost in US dollars of writing `context_tokens` to the prompt cache on the session's model, excluding the response | | ||||
| 1277 | + | ||||
| 1278 | +This example shows the input for a session resumed 90 minutes after its last response: | ||||
| 1279 | + | ||||
| 1280 | +```json theme={null} | ||||
| 1281 | +{ | ||||
| 1282 | + "session_id": "abc123", | ||||
| 1283 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 1284 | + "cwd": "/Users/...", | ||||
| 1285 | + "hook_event_name": "SessionStart", | ||||
| 1286 | + "source": "resume", | ||||
| 1287 | + "model": "claude-opus-5", | ||||
| 1288 | + "seconds_since_last_response": 5400, | ||||
| 1289 | + "context_tokens": 182340, | ||||
| 1290 | + "prompt_cache_likely_expired": true, | ||||
| 1291 | + "estimated_cache_write_usd": 1.1396 | ||||
| 1292 | +} | ||||
| 1293 | +``` | ||||
| 1294 | + | ||||
| 1295 | +#### SessionStart decision control | ||||
| 1296 | + | ||||
| 1297 | +A SessionStart hook can add context for Claude, supply the first user message, set the session title, watch files, and reload skills. Return the field for each one, in addition to the [JSON output fields](#json-output) available to all hooks: | ||||
| 1298 | + | ||||
| 1299 | +| Field | Description | | ||||
| 1300 | +| :- | :- | | ||||
| 1301 | +| `additionalContext` | String added to Claude's context at the start of the conversation, before the first prompt. See [Add context for Claude](#add-context-for-claude) for how the text is delivered and what to put in it | | ||||
| 1302 | +| `initialUserMessage` | String used as the first user message of the session, in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. It becomes the first turn even if you pass no prompt. A prompt you do pass follows as the next turn | | ||||
| 1303 | +| `sessionTitle` | Sets the session title, with the same effect as `/rename`. Applies when `source` is `"startup"`, `"resume"`, or `"fork"` | | ||||
| 1304 | +| `watchPaths` | Array of absolute paths to watch for [FileChanged](#filechanged) events during this session | | ||||
| 1305 | +| `reloadSkills` | Boolean. When `true`, Claude Code re-scans the [skill](https://code.claude.com/docs/en/skills.md) and command directories after the SessionStart hooks complete. See [Reload skills that a hook installs](#reload-skills-that-a-hook-installs) | | ||||
| 1306 | + | ||||
| 1307 | +This output adds context and names the session: | ||||
| 1308 | + | ||||
| 1309 | +```json theme={null} | ||||
| 1310 | +{ | ||||
| 1311 | + "hookSpecificOutput": { | ||||
| 1312 | + "hookEventName": "SessionStart", | ||||
| 1313 | + "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2", | ||||
| 1314 | + "sessionTitle": "auth-refactor" | ||||
| 1315 | + } | ||||
| 1316 | +} | ||||
| 1317 | +``` | ||||
| 1318 | + | ||||
| 1319 | +A hook that only adds context can print it without building JSON, because Claude Code adds a SessionStart hook's [plain-text stdout](#exit-code-0) to Claude's context. | ||||
| 1320 | + | ||||
| 1321 | +If your plugin's SessionStart hook supplies `initialUserMessage` or `sessionTitle`, install the plugin before the session starts. Claude Code ignores both fields from a plugin that finishes installing after the SessionStart hooks have run. | ||||
| 1322 | + | ||||
| 1323 | +#### Reload skills that a hook installs | ||||
| 1324 | + | ||||
| 1325 | +To make skills that a SessionStart hook installs available in the same session, return `reloadSkills`. Skill discovery normally runs before SessionStart hooks finish, so without it, files a hook writes into `~/.claude/skills/` or `.claude/skills/` can be missing when the first prompt runs. | ||||
| 1326 | + | ||||
| 1327 | +This example syncs a shared skills repository and requests the re-scan: | ||||
| 1328 | + | ||||
| 1329 | +```bash theme={null} | ||||
| 1330 | +#!/bin/bash | ||||
| 1331 | + | ||||
| 1332 | +git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \ | ||||
| 1333 | + git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills | ||||
| 1334 | + | ||||
| 1335 | +echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}' | ||||
| 1336 | +``` | ||||
| 1337 | + | ||||
| 1338 | +The repository URL is a placeholder. Replace it with your own skills repository. | ||||
| 1339 | + | ||||
| 1340 | +#### Persist environment variables | ||||
| 1341 | + | ||||
| 1342 | +SessionStart hooks have access to the `CLAUDE_ENV_FILE` environment variable, which provides a file path where you can persist environment variables for the shell commands Claude runs later in the session. | ||||
| 1343 | + | ||||
| 1344 | +To set individual environment variables, write `export` statements to `CLAUDE_ENV_FILE`. Use append (`>>`) to preserve variables set by other hooks: | ||||
| 1345 | + | ||||
| 1346 | +```bash theme={null} | ||||
| 1347 | +#!/bin/bash | ||||
| 1348 | + | ||||
| 1349 | +if [ -n "$CLAUDE_ENV_FILE" ]; then | ||||
| 1350 | + echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE" | ||||
| 1351 | + echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE" | ||||
| 1352 | + echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE" | ||||
| 1353 | +fi | ||||
| 1354 | + | ||||
| 1355 | +exit 0 | ||||
| 1356 | +``` | ||||
| 1357 | + | ||||
| 1358 | +To capture all environment changes from setup commands, compare the exported variables before and after: | ||||
| 1359 | + | ||||
| 1360 | +```bash theme={null} | ||||
| 1361 | +#!/bin/bash | ||||
| 1362 | + | ||||
| 1363 | +ENV_BEFORE=$(export -p | sort) | ||||
| 1364 | + | ||||
| 1365 | +# Run your setup commands that modify the environment | ||||
| 1366 | +source ~/.nvm/nvm.sh | ||||
| 1367 | +nvm use 20 | ||||
| 1368 | + | ||||
| 1369 | +if [ -n "$CLAUDE_ENV_FILE" ]; then | ||||
| 1370 | + ENV_AFTER=$(export -p | sort) | ||||
| 1371 | + comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE" | ||||
| 1372 | +fi | ||||
| 1373 | + | ||||
| 1374 | +exit 0 | ||||
| 1375 | +``` | ||||
| 1376 | + | ||||
| 1377 | +Each Bash command runs the file's contents as shell code before the command itself, so a line there can use anything Bash evaluates, such as the `$PATH` reference in `export PATH="$PATH:./node_modules/.bin"`. | ||||
| 1378 | + | ||||
| 1379 | +##### Persisted variables in PowerShell commands | ||||
| 1380 | + | ||||
| 1381 | +[PowerShell](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) commands receive the variables from `CLAUDE_ENV_FILE` too, in Claude Code v2.1.296 or later, but PowerShell never runs the file. Claude Code reads the assignments out of it and copies them into the PowerShell command's environment instead. It does so only when every line is one of the following, across what every hook in this session wrote and any script you [set `CLAUDE_ENV_FILE` to](https://code.claude.com/docs/en/env-vars) before launch: | ||||
| 1382 | + | ||||
| 1383 | +* A blank line or a `#` comment | ||||
| 1384 | +* One assignment at the start of the line, written `export NAME=value`, `declare -x NAME=value`, or `NAME=value`, with a value Bash would use exactly as written, made of any mix of these parts: unquoted text that uses only letters, digits, and the characters `_ @ % + = : , . / -`, text in single quotes, and text in double quotes where any `$`, backtick, or `"` inside is escaped with a backslash | ||||
| 1385 | + | ||||
| 1386 | +If any line is of another kind, such as `export PATH="$PATH:./node_modules/.bin"` with its unescaped `$PATH`, a `source` command, or the `$'...'` strings that `direnv export bash` prints, PowerShell commands receive none of the variables, and `claude --debug` logs `Session environment is not all plain assignments`. Bash commands still receive all of them. On Windows, PowerShell commands also don't receive a variable whose value contains `/` or `\`, because Git Bash and Windows write paths differently. A [sandboxed](https://code.claude.com/docs/en/sandboxing.md) PowerShell command receives none of the variables. | ||||
| 1387 | + | ||||
| 1388 | +> [!NOTE] | ||||
| 1389 | +> | ||||
| 1390 | +> `CLAUDE_ENV_FILE` is available for SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), and [FileChanged](#filechanged) hooks. Other hook events don't have access to this variable, and neither does a hook that runs in PowerShell, whether through [`"shell": "powershell"`](#command-hook-fields) or by default on Windows without Git Bash. | ||||
| 1391 | + | ||||
| 1392 | +### Setup | ||||
| 1393 | + | ||||
| 1394 | +Fires only when you launch Claude Code with `--init-only`, or with `--init` or `--maintenance` in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. It doesn't fire on normal startup. Use it for one-time dependency installation or scheduled cleanup that you trigger explicitly from CI or scripts, separate from normal session startup. For per-session initialization, use [SessionStart](#sessionstart) instead. | ||||
| 1395 | + | ||||
| 1396 | +The matcher value corresponds to the CLI flag that triggered the hook: | ||||
| 1397 | + | ||||
| 1398 | +| Matcher | When it fires | | ||||
| 1399 | +| :- | :- | | ||||
| 1400 | +| `init` | `claude --init-only` or `claude -p --init` | | ||||
| 1401 | +| `maintenance` | `claude -p --maintenance` | | ||||
| 1402 | + | ||||
| 1403 | +When you run `claude --init-only`, Claude Code runs Setup hooks and `SessionStart` hooks with the `startup` matcher, then exits without starting a conversation. | ||||
| 1404 | + | ||||
| 1405 | +When you start or continue a conversation with `-p`, you also need to supply a prompt, as an argument or piped on stdin. You can skip the prompt when a `SessionStart` hook supplies [`initialUserMessage`](#sessionstart-decision-control) or when you resume a session with a [deferred tool call](#defer-a-tool-call-for-later). | ||||
| 1406 | + | ||||
| 1407 | +On success, `--init-only` prints nothing to the terminal. To confirm the hooks ran, start with `claude --debug-file <path> --init-only`, replacing `<path>` with a log file location, and check the log for the Setup and SessionStart hook entries. | ||||
| 1408 | + | ||||
| 1409 | +Because Setup doesn't fire on every launch, a plugin that needs a dependency installed can't rely on Setup alone. The practical pattern is to check for the dependency on first use and install on miss, for example a hook or skill that tests for `${CLAUDE_PLUGIN_DATA}/node_modules` and runs `npm install` if absent. See the [persistent data directory](https://code.claude.com/docs/en/plugins/components.md#path-variables-and-persistent-data) for where to store installed dependencies. If you distribute your plugin through a marketplace, you may not need this pattern: Claude Code [installs eligible Node.js package dependencies automatically](https://code.claude.com/docs/en/plugins/loading.md#node-js-package-dependencies) when it caches the plugin. | ||||
| 1410 | + | ||||
| 1411 | +#### Setup input | ||||
| 1412 | + | ||||
| 1413 | +In addition to the [common input fields](#common-input-fields), Setup hooks receive a `trigger` field set to either `"init"` or `"maintenance"`: | ||||
| 1414 | + | ||||
| 1415 | +```json theme={null} | ||||
| 1416 | +{ | ||||
| 1417 | + "session_id": "abc123", | ||||
| 1418 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 1419 | + "cwd": "/Users/...", | ||||
| 1420 | + "hook_event_name": "Setup", | ||||
| 1421 | + "trigger": "init" | ||||
| 1422 | +} | ||||
| 1423 | +``` | ||||
| 1424 | + | ||||
| 1425 | +#### Setup decision control | ||||
| 1426 | + | ||||
| 1427 | +Setup hooks can't block; execution continues on any exit code. On every exit code, Claude Code discards a Setup hook's [JSON output fields](#json-output), such as `systemMessage`, `continue`, and `hookSpecificOutput.additionalContext`. With `-p`, a Setup hook's stdout, stderr, and exit code appear in the run's output only as [`hook_response` events](https://code.claude.com/docs/en/headless#read-session-metadata) when you launch with `--output-format stream-json --verbose`. | ||||
| 1428 | + | ||||
| 1429 | +Setup hooks have access to `CLAUDE_ENV_FILE`. If your hook writes variables to that file, they persist into subsequent Bash commands for the session, as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks run on `Setup`. A `type: "mcp_tool"` hook on `Setup` is always skipped, as described under [MCP tool hook fields](#mcp-tool-hook-fields). | ||||
| 1430 | + | ||||
| 1431 | +### InstructionsLoaded | ||||
| 1432 | + | ||||
| 1433 | +Fires when a `CLAUDE.md` or `.claude/rules/*.md` file is loaded into context. This event fires at session start for eagerly loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested `CLAUDE.md` or when conditional rules with `paths:` frontmatter match. The hook doesn't support blocking or decision control. It runs asynchronously for observability purposes. | ||||
| 1434 | + | ||||
| 1435 | +This event doesn't fire when Claude [reads `AGENTS.md` directly](https://code.claude.com/docs/en/memory#agents-md) through the **Project instructions** setting. It does fire when a `CLAUDE.md` imports your `AGENTS.md`, with `load_reason` set to `include` as for any other imported file, and when `CLAUDE.md` is a symlink to it, as a normal `CLAUDE.md` load. | ||||
| 1436 | + | ||||
| 1437 | +The matcher runs against `load_reason`. For example, use `"matcher": "session_start"` to fire only for files loaded at session start, or `"matcher": "path_glob_match|nested_traversal"` to fire only for lazy loads. | ||||
| 1438 | + | ||||
| 1439 | +#### InstructionsLoaded input | ||||
| 1440 | + | ||||
| 1441 | +In addition to the [common input fields](#common-input-fields), InstructionsLoaded hooks receive these fields: | ||||
| 1442 | + | ||||
| 1443 | +| Field | Description | | ||||
| 1444 | +| :- | :- | | ||||
| 1445 | +| `file_path` | Absolute path to the instruction file that was loaded | | ||||
| 1446 | +| `memory_type` | Scope of the file: `"User"`, `"Project"`, `"Local"`, or `"Managed"` | | ||||
| 1447 | +| `load_reason` | Why the file was loaded: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"`, or `"compact"`. The `"compact"` value fires when instruction files are re-loaded after a compaction event | | ||||
| 1448 | +| `globs` | Path glob patterns from the file's `paths:` frontmatter, if any. Present only for `path_glob_match` loads | | ||||
| 1449 | +| `trigger_file_path` | Path to the file whose access triggered this load, for lazy loads | | ||||
| 1450 | +| `parent_file_path` | Path to the parent instruction file that included this one, for `include` loads | | ||||
| 1451 | + | ||||
| 1452 | +```json theme={null} | ||||
| 1453 | +{ | ||||
| 1454 | + "session_id": "abc123", | ||||
| 1455 | + "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl", | ||||
| 1456 | + "cwd": "/Users/my-project", | ||||
| 1457 | + "hook_event_name": "InstructionsLoaded", | ||||
| 1458 | + "file_path": "/Users/my-project/CLAUDE.md", | ||||
| 1459 | + "memory_type": "Project", | ||||
| 1460 | + "load_reason": "session_start" | ||||
| 1461 | +} | ||||
| 1462 | +``` | ||||
| 1463 | + | ||||
| 1464 | +#### InstructionsLoaded decision control | ||||
| 1465 | + | ||||
| 1466 | +InstructionsLoaded hooks have no decision control. They can't block or modify instruction loading. Claude Code discards their [JSON output fields](#json-output), such as `systemMessage` and `continue`. Use this event for audit logging, compliance tracking, or observability. | ||||
| 1467 | + | ||||
| 1468 | +### UserPromptSubmit | ||||
| 1469 | + | ||||
| 1470 | +Runs when a prompt is submitted, before Claude processes it. This allows you | ||||
| 1471 | +to add additional context based on the prompt/conversation, validate prompts, or | ||||
| 1472 | +block certain types of prompts. | ||||
| 1473 | + | ||||
| 1474 | +`UserPromptSubmit` hooks don't fire only on prompts you type. Claude Code also runs them on: | ||||
| 1475 | + | ||||
| 1476 | +* A [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) firing, including a `/loop` iteration | ||||
| 1477 | +* A [background subagent](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) reporting back to the session that started it | ||||
| 1478 | +* A [message another session sends](https://code.claude.com/docs/en/cross-session-messaging.md) to your main conversation | ||||
| 1479 | + | ||||
| 1480 | +`UserPromptSubmit` hooks have a default timeout of 30 seconds for `command`, `http`, and `mcp_tool` types, shorter than the 600-second default for those types on most other events. Because this hook runs before every prompt and blocks model processing until it completes, a stuck hook stalls the session. If your hook needs more time, set the `timeout` field in the hook entry. | ||||
| 1481 | + | ||||
| 1482 | +Apart from a command hook you run with [`async: true`](#run-hooks-in-the-background), a `UserPromptSubmit` command, HTTP, or MCP tool hook that reaches its timeout is canceled and its output, including any `additionalContext`, is discarded. The prompt still reaches Claude without that context. To block the prompt instead, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails) on a command or HTTP hook. The transcript shows a notice naming the hook, the timeout that fired, and that the output was discarded. | ||||
| 1483 | + | ||||
| 1484 | +An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md) on `UserPromptSubmit` that reaches its timeout blocks the prompt with a message naming the hook and the timeout, because a callback there can be acting as a policy gate that must not fail open. The session continues. | ||||
| 1485 | + | ||||
| 1486 | +#### `Esc` during a prompt check | ||||
| 1487 | + | ||||
| 1488 | +If you press `Esc` or interrupt the session while hooks are still checking a prompt, the check stops and the prompt doesn't reach Claude. Text you typed at the terminal returns to the prompt input, and the hooks check it again when you resend it. | ||||
| 1489 | + | ||||
| 1490 | +A hook can block the prompt at the same moment you interrupt. The prompt then stays blocked: you see that hook's [block message](#what-a-blocked-prompt-leaves-behind), and the text doesn't return to the input. | ||||
| 1491 | + | ||||
| 1492 | +#### UserPromptSubmit input | ||||
| 1493 | + | ||||
| 1494 | +In addition to the [common input fields](#common-input-fields), UserPromptSubmit hooks receive the `prompt` field containing the submitted text. Pasted content that collapsed to a `[Pasted text #N]` placeholder arrives expanded in place. In sessions where Claude Code [marks pasted text for Claude](https://code.claude.com/docs/en/terminal-config.md#how-claude-treats-pasted-text), that expanded content sits between a `<pasted_content id="…">` line and a `</pasted_content id="…">` line, so account for those lines if your hook parses the prompt. | ||||
| 1495 | + | ||||
| 1496 | +UserPromptSubmit hooks also receive `session_title` when the session has a custom title, with the same meaning as the [SessionStart `session_title` field](#sessionstart-input). | ||||
| 1497 | + | ||||
| 1498 | +```json theme={null} | ||||
| 1499 | +{ | ||||
| 1500 | + "session_id": "abc123", | ||||
| 1501 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 1502 | + "cwd": "/Users/...", | ||||
| 1503 | + "permission_mode": "default", | ||||
| 1504 | + "hook_event_name": "UserPromptSubmit", | ||||
| 1505 | + "prompt": "Write a function to calculate the factorial of a number" | ||||
| 1506 | +} | ||||
| 1507 | +``` | ||||
| 1508 | + | ||||
| 1509 | +When the prompt is a [skill](https://code.claude.com/docs/en/skills.md) or custom command you typed, such as `/deploy staging`, the hook receives that line as you typed it rather than the expanded skill content. If the hook blocks the prompt, the command doesn't run, so shell commands the skill [injects with `` !`<command>` ``](https://code.claude.com/docs/en/skills#inject-dynamic-context) don't run either. To match on the command's name or arguments instead, use [UserPromptExpansion](#userpromptexpansion). | ||||
| 1510 | + | ||||
| 1511 | +#### UserPromptSubmit decision control | ||||
| 1512 | + | ||||
| 1513 | +`UserPromptSubmit` hooks can control whether a submitted prompt is processed and add context. All [JSON output fields](#json-output) are available. | ||||
| 1514 | + | ||||
| 1515 | +There are two ways to add context to the conversation on exit code 0: | ||||
| 1516 | + | ||||
| 1517 | +* **Plain text stdout**: Claude Code adds stdout it [treats as plain text](#exit-code-0) to Claude's context | ||||
| 1518 | +* **JSON with `additionalContext`**: use the JSON format below for more control. The `additionalContext` field is added as context | ||||
| 1519 | + | ||||
| 1520 | +Neither channel produces a visible transcript entry. Plain stdout and the `additionalContext` value are each injected as a system reminder that starts with the hook's name; Claude reads both. To confirm delivery, check the [debug log](#debug-hooks). | ||||
| 1521 | + | ||||
| 1522 | +To block a prompt, return a JSON object with `decision` set to `"block"`: | ||||
| 1523 | + | ||||
| 1524 | +| Field | Description | | ||||
| 1525 | +| :- | :- | | ||||
| 1526 | +| `decision` | `"block"` stops the prompt before it reaches Claude. Omit to allow the prompt to proceed | | ||||
| 1527 | +| `reason` | Shown to the user when `decision` is `"block"`. Not added to context | | ||||
| 1528 | +| `additionalContext` | String added to Claude's context alongside the submitted prompt. See [Add context for Claude](#add-context-for-claude) | | ||||
| 1529 | +| `sessionTitle` | Sets the session title. Use to name sessions automatically based on the prompt content | | ||||
| 1530 | +| `suppressOriginalPrompt` | If `true` when the hook blocks the prompt, leaves the prompt text out of the block message. See [What a blocked prompt leaves behind](#what-a-blocked-prompt-leaves-behind) | | ||||
| 1531 | + | ||||
| 1532 | +A hook that blocks by exiting 2 routes the same way as `reason`: the block message shows the stderr text to the user, and it isn't added to context. | ||||
| 1533 | + | ||||
| 1534 | +```json theme={null} | ||||
| 1535 | +{ | ||||
| 1536 | + "decision": "block", | ||||
| 1537 | + "reason": "Explanation for decision", | ||||
| 1538 | + "hookSpecificOutput": { | ||||
| 1539 | + "hookEventName": "UserPromptSubmit", | ||||
| 1540 | + "additionalContext": "My additional context here", | ||||
| 1541 | + "sessionTitle": "My session title", | ||||
| 1542 | + "suppressOriginalPrompt": true | ||||
| 1543 | + } | ||||
| 1544 | +} | ||||
| 1545 | +``` | ||||
| 1546 | + | ||||
| 1547 | +#### What a blocked prompt leaves behind | ||||
| 1548 | + | ||||
| 1549 | +A blocked prompt never reaches Claude, but its text isn't removed everywhere. By default the block message shown to the user ends with `Original prompt:` followed by the submitted text, and Claude Code writes that message to the session's transcript file on disk. To leave the text out of the message, print JSON with `"suppressOriginalPrompt": true` inside `hookSpecificOutput`. This works whether the hook blocks with `decision: "block"` or by exiting 2. | ||||
| 1550 | + | ||||
| 1551 | +`suppressOriginalPrompt` changes only the block message. The submitted text can still appear in local files such as the session transcript and your prompt history, so a blocking hook isn't a way to keep a secret off disk. To limit or remove those files, see [Plaintext storage](https://code.claude.com/docs/en/claude-directory.md#plaintext-storage) and [Clear local data](https://code.claude.com/docs/en/claude-directory.md#clear-local-data). | ||||
| 1552 | + | ||||
| 1553 | +### UserPromptExpansion | ||||
| 1554 | + | ||||
| 1555 | +Runs when a user-typed command expands into a prompt before reaching Claude. Use this to block specific commands from direct invocation, inject context for a particular skill, or log which commands users invoke. For example, a hook matching `deploy` can block `/deploy` unless an approval file is present, or a hook matching a review skill can append the team's review checklist as `additionalContext`. | ||||
| 1556 | + | ||||
| 1557 | +This event covers the path `PreToolUse` doesn't: a `PreToolUse` hook matching the `Skill` tool fires only when Claude calls the tool, but typing `/skillname` directly bypasses `PreToolUse`. `UserPromptExpansion` fires on that direct path. | ||||
| 1558 | + | ||||
| 1559 | +Matches on `command_name`. Leave the matcher empty to fire on every prompt-type command. | ||||
| 1560 | + | ||||
| 1561 | +#### UserPromptExpansion input | ||||
| 1562 | + | ||||
| 1563 | +In addition to the [common input fields](#common-input-fields), UserPromptExpansion hooks receive `expansion_type`, `command_name`, `command_args`, `command_source`, and the original `prompt` string. The `expansion_type` field is `slash_command` for skill and custom commands, or `mcp_prompt` for MCP server prompts. | ||||
| 1564 | + | ||||
| 1565 | +```json theme={null} | ||||
| 1566 | +{ | ||||
| 1567 | + "session_id": "abc123", | ||||
| 1568 | + "transcript_path": "/Users/.../00893aaf.jsonl", | ||||
| 1569 | + "cwd": "/Users/...", | ||||
| 1570 | + "permission_mode": "default", | ||||
| 1571 | + "hook_event_name": "UserPromptExpansion", | ||||
| 1572 | + "expansion_type": "slash_command", | ||||
| 1573 | + "command_name": "example-skill", | ||||
| 1574 | + "command_args": "arg1 arg2", | ||||
| 1575 | + "command_source": "plugin", | ||||
| 1576 | + "prompt": "/example-skill arg1 arg2" | ||||
| 1577 | +} | ||||
| 1578 | +``` | ||||
| 1579 | + | ||||
| 1580 | +#### UserPromptExpansion decision control | ||||
| 1581 | + | ||||
| 1582 | +`UserPromptExpansion` hooks can block the expansion or add context. All [JSON output fields](#json-output) are available. | ||||
| 1583 | + | ||||
| 1584 | +| Field | Description | | ||||
| 1585 | +| :- | :- | | ||||
| 1586 | +| `decision` | `"block"` prevents the command from expanding. Omit to allow it to proceed | | ||||
| 1587 | +| `reason` | Shown to the user when `decision` is `"block"` | | ||||
| 1588 | +| `additionalContext` | String added to Claude's context alongside the expanded prompt. See [Add context for Claude](#add-context-for-claude) | | ||||
| 1589 | + | ||||
| 1590 | +A hook that blocks by exiting 2 routes the same way as `reason`: the block message shows the stderr text to the user. | ||||
| 1591 | + | ||||
| 1592 | +```json theme={null} | ||||
| 1593 | +{ | ||||
| 1594 | + "decision": "block", | ||||
| 1595 | + "reason": "This slash command is not available", | ||||
| 1596 | + "hookSpecificOutput": { | ||||
| 1597 | + "hookEventName": "UserPromptExpansion", | ||||
| 1598 | + "additionalContext": "Additional context for this expansion" | ||||
| 1599 | + } | ||||
| 1600 | +} | ||||
| 1601 | +``` | ||||
| 1602 | + | ||||
| 1603 | +### MessageDisplay | ||||
| 1604 | + | ||||
| 1605 | +Runs while an assistant message streams to the screen. Claude Code displays the message in increments: each time a batch of newly completed lines is ready to render, the hook runs once with those lines and Claude Code renders the hook's replacement text in their place. A long message produces several calls; a short message may produce only one. | ||||
| 1606 | + | ||||
| 1607 | +Use MessageDisplay to: | ||||
| 1608 | + | ||||
| 1609 | +* strip markdown for a minimal display | ||||
| 1610 | +* transform the text an Agent SDK application shows its users | ||||
| 1611 | +* redact API keys or internal hostnames from Claude's responses | ||||
| 1612 | + | ||||
| 1613 | +Claude Code holds each batch until your hook returns, so keep the hook fast. If the hook fails or times out, Claude Code displays the original text. The default timeout for this event is 10 seconds; if your hook needs more time, set the `timeout` field in the hook entry. | ||||
| 1614 | + | ||||
| 1615 | +MessageDisplay is display-only: the replacement text changes only what is rendered on screen. The transcript and what Claude sees keep the original text, so Claude never sees the replacement, and verbose mode shows the original. The hook receives assistant message text only, so tool results and the text you type render unchanged. | ||||
| 1616 | + | ||||
| 1617 | +MessageDisplay doesn't support matchers and fires for every assistant message that streams text; messages with no text, such as tool-call-only responses, don't trigger it. | ||||
| 1618 | + | ||||
| 1619 | +In non-interactive runs, including Agent SDK queries and `claude -p`, MessageDisplay runs once per assistant message instead of once per batch of lines. The single call arrives after the message completes and carries the full message text: `index` is `0`, `final` is `true`, and `delta` holds the entire message. A hook that collects the `delta` text for each message receives the same total text in both modes. | ||||
| 1620 | + | ||||
| 1621 | +#### MessageDisplay input | ||||
| 1622 | + | ||||
| 1623 | +In addition to the [common input fields](#common-input-fields), MessageDisplay hooks receive identifiers for the turn and message, the position of this call within the message, and the new text in `delta`. Batch boundaries depend on how the text streams, so use `index` and `final` to track progress through a message rather than expecting lines to be grouped a particular way. | ||||
| 1624 | + | ||||
| 1625 | +| Field | Description | | ||||
| 1626 | +| :- | :- | | ||||
| 1627 | +| `turn_id` | UUID of the current turn | | ||||
| 1628 | +| `message_id` | UUID of the assistant message being displayed. Stable across every batch of the same message. This is not the API `msg_…` id, so it can't be correlated with transcript message ids | | ||||
| 1629 | +| `index` | Zero-based index of this batch within the message | | ||||
| 1630 | +| `final` | `true` on the message's last batch. Each message has exactly one final batch | | ||||
| 1631 | +| `delta` | The newly completed lines since the prior batch, terminating newlines included. Always whole lines, except the final batch which may end mid-line. In interactive runs, the final batch's delta is empty when the message ends on a newline, so treat `final`, not a non-empty delta, as the end-of-message signal. In Agent SDK and `claude -p` runs, the single call carries the entire message | | ||||
| 1632 | + | ||||
| 1633 | +```json theme={null} | ||||
| 1634 | +{ | ||||
| 1635 | + "session_id": "abc123", | ||||
| 1636 | + "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl", | ||||
| 1637 | + "cwd": "/Users/my-project", | ||||
| 1638 | + "hook_event_name": "MessageDisplay", | ||||
| 1639 | + "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10", | ||||
| 1640 | + "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b", | ||||
| 1641 | + "index": 0, | ||||
| 1642 | + "final": false, | ||||
| 1643 | + "delta": "Here is the plan:\n" | ||||
| 1644 | +} | ||||
| 1645 | +``` | ||||
| 1646 | + | ||||
| 1647 | +#### MessageDisplay output | ||||
| 1648 | + | ||||
| 1649 | +In addition to the [JSON output fields](#json-output) available to all hooks, MessageDisplay hooks can return `displayContent` to replace the delta on screen: | ||||
| 1650 | + | ||||
| 1651 | +| Field | Description | | ||||
| 1652 | +| :- | :- | | ||||
| 1653 | +| `displayContent` | Text displayed in place of the delta. Omit it to display the original | | ||||
| 1654 | + | ||||
| 1655 | +MessageDisplay hooks have no decision control. They can't block the message or change what is stored in the transcript or sent to Claude. Claude Code acts on `displayContent` from their JSON output and discards `systemMessage` and `continue`. | ||||
| 1656 | + | ||||
| 1657 | +This example strips markdown formatting from Claude's responses for a plain-text display. The script reads each batch from stdin, removes bold markers and inline code backticks from `delta`, and returns the result as `displayContent`. | ||||
| 1658 | + | ||||
| 1659 | +**macOS/Linux** | ||||
| 1660 | + | ||||
| 1661 | +Register a command hook for the event in your settings file: | ||||
| 1662 | + | ||||
| 1663 | +```json theme={null} | ||||
| 1664 | +{ | ||||
| 1665 | + "hooks": { | ||||
| 1666 | + "MessageDisplay": [ | ||||
| 1667 | + { | ||||
| 1668 | + "hooks": [ | ||||
| 1669 | + { | ||||
| 1670 | + "type": "command", | ||||
| 1671 | + "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh", | ||||
| 1672 | + "args": [] | ||||
| 1673 | + } | ||||
| 1674 | + ] | ||||
| 1675 | + } | ||||
| 1676 | + ] | ||||
| 1677 | + } | ||||
| 1678 | +} | ||||
| 1679 | +``` | ||||
| 1680 | + | ||||
| 1681 | +Save this script to `.claude/hooks/plain-display.sh` in your project and make it executable with `chmod +x`: | ||||
| 1682 | + | ||||
| 1683 | +```bash theme={null} | ||||
| 1684 | +#!/bin/bash | ||||
| 1685 | +jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}' | ||||
| 1686 | +``` | ||||
| 1687 | + | ||||
| 1688 | +**Windows (PowerShell)** | ||||
| 1689 | + | ||||
| 1690 | +Register a command hook that runs the script through PowerShell: | ||||
| 1691 | + | ||||
| 1692 | +```json theme={null} | ||||
| 1693 | +{ | ||||
| 1694 | + "hooks": { | ||||
| 1695 | + "MessageDisplay": [ | ||||
| 1696 | + { | ||||
| 1697 | + "hooks": [ | ||||
| 1698 | + { | ||||
| 1699 | + "type": "command", | ||||
| 1700 | + "command": "powershell.exe", | ||||
| 1701 | + "args": [ | ||||
| 1702 | + "-NoProfile", | ||||
| 1703 | + "-ExecutionPolicy", | ||||
| 1704 | + "Bypass", | ||||
| 1705 | + "-File", | ||||
| 1706 | + "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1" | ||||
| 1707 | + ] | ||||
| 1708 | + } | ||||
| 1709 | + ] | ||||
| 1710 | + } | ||||
| 1711 | + ] | ||||
| 1712 | + } | ||||
| 1713 | +} | ||||
| 1714 | +``` | ||||
| 1715 | + | ||||
| 1716 | +The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file. | ||||
| 1717 | + | ||||
| 1718 | +Save this script to `.claude/hooks/plain-display.ps1` in your project: | ||||
| 1719 | + | ||||
| 1720 | +```powershell theme={null} | ||||
| 1721 | +$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json | ||||
| 1722 | +$text = $batch.delta -replace '\*\*', '' -replace '`', '' | ||||
| 1723 | +@{ | ||||
| 1724 | + hookSpecificOutput = @{ | ||||
| 1725 | + hookEventName = "MessageDisplay" | ||||
| 1726 | + displayContent = $text | ||||
| 1727 | + } | ||||
| 1728 | +} | ConvertTo-Json | ||||
| 1729 | +``` | ||||
| 1730 | + | ||||
| 1731 | +Batches with no markdown pass through unchanged. If the script fails, for example because `jq` is missing, Claude Code displays the original text and notes the failure only in [debug output](#debug-hooks), not in the session. | ||||
| 1732 | + | ||||
| 1733 | +### PreToolUse | ||||
| 1734 | + | ||||
| 1735 | +Runs after Claude creates tool parameters and before processing the tool call. Matches on any tool name except `EndConversation`: built-in tools such as `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion`, and `ExitPlanMode`, and any [MCP tool names](#match-mcp-tools). | ||||
| 1736 | + | ||||
| 1737 | +To run a hook when a specific file changes on disk, whatever wrote it, use [FileChanged](#filechanged) instead of matching file-editing tools by name. Unlike PreToolUse, Claude Code runs FileChanged hooks after the change, and they have no decision control, so they can't block the write. | ||||
| 1738 | + | ||||
| 1739 | +> [!WARNING] | ||||
| 1740 | +> | ||||
| 1741 | +> PreToolUse runs only when Claude calls a tool. By default, files you [reference with `@` in your prompt](https://code.claude.com/docs/en/common-workflows#reference-files-and-directories) are added without any tool call. Claude Code inserts their contents while building the prompt, so no PreToolUse hook fires for them, including hooks matching `Read`. PreToolUse also doesn't fire for [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior). | ||||
| 1742 | +> | ||||
| 1743 | +> You can block specific paths from `@` references, or turn the insertion off: | ||||
| 1744 | +> | ||||
| 1745 | +> * **Block specific paths**: add a [`Read` deny rule](https://code.claude.com/docs/en/permissions#read-and-edit) for them | ||||
| 1746 | +> * **Turn the insertion off**: set [`CLAUDE_CODE_DISABLE_FILE_MENTIONS=1`](https://code.claude.com/docs/en/env-vars#variables) in your shell, user settings, or managed settings. Claude then gets the mentioned paths with a note to read them using its file tools. If it does, your matching PreToolUse hooks run. The variable requires Claude Code v2.1.299 or later, and Claude Code ignores it in project and local settings. | ||||
| 1747 | + | ||||
| 1748 | +Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, ask, or defer the tool call. | ||||
| 1749 | + | ||||
| 1750 | +An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md#hook-timeout) on `PreToolUse` that exceeds its timeout blocks the tool call. | ||||
| 1751 | + | ||||
| 1752 | +#### PreToolUse input | ||||
| 1753 | + | ||||
| 1754 | +In addition to the [common input fields](#common-input-fields), PreToolUse hooks receive `tool_name`, `tool_input`, and `tool_use_id`. | ||||
| 1755 | + | ||||
| 1756 | +For an [MCP tool](#match-mcp-tools), the input also carries `mcp_server`, an object with the server's `name` and a `source` that says where the server's definition came from. The `source` values include `plugin`, `sdk`, and configuration scopes such as `user` and `project`. [`McpServerProvenance`](https://code.claude.com/docs/en/agent-sdk/typescript#mcpserverprovenance) in the Agent SDK reference lists them all and says how to treat one you don't recognize. Base trust decisions on `source` rather than on `name` or the `mcp__<server>__` tool-name prefix. The `mcp_server` field requires Claude Code v2.1.274 or later. | ||||
| 1757 | + | ||||
| 1758 | +For the file tools `Write`, `Edit`, and `Read`, `tool_input.file_path` is always absolute: | ||||
| 1759 | + | ||||
| 1760 | +* Claude Code expands `~` and relative paths before hooks run, so a hook that matches on paths can't be bypassed via `~` or a relative spelling of the same path | ||||
| 1761 | +* On Windows, the path arrives with backslash separators, even when your hook runs under Git Bash where `$PWD` looks like `/c/project` | ||||
| 1762 | +* A comparison written with forward slashes, such as a `/src/` check, never matches a backslash path, and the tool call proceeds as if the hook had nothing to block | ||||
| 1763 | +* Normalize separators before comparing: `FILE_PATH="${FILE_PATH//\\//}"` in Bash, or `file_path.replace("\\", "/")` in Python, then match a path segment such as `/src/` rather than anchoring with `^`, since the path is absolute | ||||
| 1764 | + | ||||
| 1765 | +A `Write` call on Windows delivers: | ||||
| 1766 | + | ||||
| 1767 | +```json theme={null} | ||||
| 1768 | +{ | ||||
| 1769 | + "hook_event_name": "PreToolUse", | ||||
| 1770 | + "tool_name": "Write", | ||||
| 1771 | + "tool_input": { | ||||
| 1772 | + "file_path": "C:\\project\\src\\index.ts", | ||||
| 1773 | + "content": "..." | ||||
| 1774 | + }, | ||||
| 1775 | + ... | ||||
| 1776 | +} | ||||
| 1777 | +``` | ||||
| 1778 | + | ||||
| 1779 | +The `tool_input` fields depend on the tool: | ||||
| 1780 | + | ||||
| 1781 | +##### Bash | ||||
| 1782 | + | ||||
| 1783 | +Executes shell commands. | ||||
| 1784 | + | ||||
| 1785 | +| Field | Type | Example | Description | | ||||
| 1786 | +| :- | :- | :- | :- | | ||||
| 1787 | +| `command` | string | `"npm test"` | The shell command to execute | | ||||
| 1788 | +| `description` | string | `"Run test suite"` | Optional description of what the command does | | ||||
| 1789 | +| `timeout` | number | `120000` | Optional timeout in milliseconds. Values above the [maximum](https://code.claude.com/docs/en/tools-reference.md#bash-tool-behavior) are reduced to the maximum rather than rejected | | ||||
| 1790 | +| `run_in_background` | boolean | `false` | Whether to run the command in background | | ||||
| 1791 | + | ||||
| 1792 | +When a Bash command changes files in a Git repository, Claude Code can record what changed. It records the changes in every permission mode when the [`bashEditDiffEnabled`](https://code.claude.com/docs/en/settings-reference#basheditdiffenabled) setting turns recording on; that setting's entry says which files can set it. Otherwise it records them only in auto mode and `bypassPermissions` mode, and only when Claude Code directs Claude to edit files through Bash. Set `bashEditDiffEnabled` to `false` to turn the recording off. Background commands and read-only commands carry no diff. | ||||
| 1793 | + | ||||
| 1794 | +Your [PostToolUse hook](#posttooluse) then receives the changed files in `tool_response.bashEditDiff`. The list covers what changed under the repository while the command ran. Files that Git ignores and files in submodules aren't listed. Requires Claude Code v2.1.269 or later. | ||||
| 1795 | + | ||||
| 1796 | +> [!NOTE] | ||||
| 1797 | +> | ||||
| 1798 | +> The list is best effort and in public beta. Claude Code can miss a change, include a file that another process changed at the same time, or stop at its size limits. The field shape may change. Use the list to find what to review, not to enforce a policy. | ||||
| 1799 | + | ||||
| 1800 | +`changedFiles` and `files` list what the command changed; the remaining fields say how complete and how reliable that list is. | ||||
| 1801 | + | ||||
| 1802 | +| Field | Type | Example | Description | | ||||
| 1803 | +| :- | :- | :- | :- | | ||||
| 1804 | +| `changedFiles` | array | `["/path/to/src/app.ts"]` | Absolute paths of the files the command changed, at most 200. Present whenever `files` holds a diff or `moreFiles` is above zero | | ||||
| 1805 | +| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs of up to 5 changed files, for display. `created` or `deleted` is `true` for a file the command added or removed | | ||||
| 1806 | +| `moreFiles` | number | `2` | Count of changed files with no diff in `files` | | ||||
| 1807 | +| `unavailable` | boolean | `true` | Set when the diff is incomplete or couldn't be taken | | ||||
| 1808 | +| `skipped` | boolean | `true` | Set for a Git command that moves the working tree, such as `git checkout` or `git stash`, so Claude Code takes no diff | | ||||
| 1809 | +| `shared` | boolean | `true` | Set when another Bash tool call, such as a subagent's, ran in the same repository at the same time, so some listed changes may be that command's | | ||||
| 1810 | + | ||||
| 1811 | +##### PowerShell | ||||
| 1812 | + | ||||
| 1813 | +Executes PowerShell commands. See the [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) for availability by platform. | ||||
| 1814 | + | ||||
| 1815 | +The fields match the Bash tool, with the command string in `command`: | ||||
| 1816 | + | ||||
| 1817 | +| Field | Type | Example | Description | | ||||
| 1818 | +| :- | :- | :- | :- | | ||||
| 1819 | +| `command` | string | `"Get-ChildItem -Recurse"` | The PowerShell command to execute | | ||||
| 1820 | +| `description` | string | `"List files recursively"` | Optional description of what the command does | | ||||
| 1821 | +| `timeout` | number | `120000` | Optional timeout in milliseconds | | ||||
| 1822 | +| `run_in_background` | boolean | `false` | Whether to run the command in background | | ||||
| 1823 | + | ||||
| 1824 | +Match `Bash|PowerShell` in hooks that inspect shell commands, so they cover both tools: | ||||
| 1825 | + | ||||
| 1826 | +* On Windows, wherever the PowerShell tool is enabled, Claude treats PowerShell as the primary shell and routes shell commands through it. | ||||
| 1827 | +* On Windows without Git Bash, the tool is enabled automatically and Claude Code doesn't register the Bash tool at all. | ||||
| 1828 | +* A hook that matches only `Bash` never fires there. | ||||
| 1829 | + | ||||
| 1830 | +##### Write | ||||
| 1831 | + | ||||
| 1832 | +Creates or overwrites a file. | ||||
| 1833 | + | ||||
| 1834 | +| Field | Type | Example | Description | | ||||
| 1835 | +| :- | :- | :- | :- | | ||||
| 1836 | +| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to write | | ||||
| 1837 | +| `content` | string | `"file content"` | Content to write to the file | | ||||
| 1838 | + | ||||
| 1839 | +##### Edit | ||||
| 1840 | + | ||||
| 1841 | +Replaces a string in an existing file. | ||||
| 1842 | + | ||||
| 1843 | +| Field | Type | Example | Description | | ||||
| 1844 | +| :- | :- | :- | :- | | ||||
| 1845 | +| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to edit | | ||||
| 1846 | +| `old_string` | string | `"original text"` | Text to find and replace | | ||||
| 1847 | +| `new_string` | string | `"replacement text"` | Replacement text | | ||||
| 1848 | +| `replace_all` | boolean | `false` | Whether to replace all occurrences | | ||||
| 1849 | + | ||||
| 1850 | +##### Read | ||||
| 1851 | + | ||||
| 1852 | +Reads file contents. | ||||
| 1853 | + | ||||
| 1854 | +| Field | Type | Example | Description | | ||||
| 1855 | +| :- | :- | :- | :- | | ||||
| 1856 | +| `file_path` | string | `"/path/to/file.txt"` | Absolute path to the file to read | | ||||
| 1857 | +| `offset` | number | `10` | Optional line number to start reading from | | ||||
| 1858 | +| `limit` | number | `50` | Optional number of lines to read | | ||||
| 1859 | + | ||||
| 1860 | +##### Glob | ||||
| 1861 | + | ||||
| 1862 | +Finds files matching a glob pattern. | ||||
| 1863 | + | ||||
| 1864 | +| Field | Type | Example | Description | | ||||
| 1865 | +| :- | :- | :- | :- | | ||||
| 1866 | +| `pattern` | string | `"**/*.ts"` | Glob pattern to match files against | | ||||
| 1867 | +| `path` | string | `"/path/to/dir"` | Optional directory to search in. Defaults to current working directory | | ||||
| 1868 | + | ||||
| 1869 | +##### Grep | ||||
| 1870 | + | ||||
| 1871 | +Searches file contents with regular expressions. | ||||
| 1872 | + | ||||
| 1873 | +| Field | Type | Example | Description | | ||||
| 1874 | +| :- | :- | :- | :- | | ||||
| 1875 | +| `pattern` | string | `"TODO.*fix"` | Regular expression pattern to search for | | ||||
| 1876 | +| `path` | string | `"/path/to/dir"` | Optional file or directory to search in | | ||||
| 1877 | +| `glob` | string | `"*.ts"` | Optional glob pattern to filter files | | ||||
| 1878 | +| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, or `"count"`. Defaults to `"files_with_matches"` | | ||||
| 1879 | +| `-i` | boolean | `true` | Case insensitive search | | ||||
| 1880 | +| `multiline` | boolean | `false` | Enable multiline matching | | ||||
| 1881 | + | ||||
| 1882 | +##### WebFetch | ||||
| 1883 | + | ||||
| 1884 | +Fetches and processes web content. | ||||
| 1885 | + | ||||
| 1886 | +| Field | Type | Example | Description | | ||||
| 1887 | +| :- | :- | :- | :- | | ||||
| 1888 | +| `url` | string | `"https://example.com/api"` | URL to fetch content from | | ||||
| 1889 | +| `prompt` | string | `"Extract the API endpoints"` | Prompt to run on the fetched content | | ||||
| 1890 | +| `offset` | number | `100000` | Optional number of characters to skip from the start of the page. Claude sets it to keep reading a long page. Requires Claude Code v2.1.290 or later | | ||||
| 1891 | + | ||||
| 1892 | +##### WebSearch | ||||
| 1893 | + | ||||
| 1894 | +Searches the web. | ||||
| 1895 | + | ||||
| 1896 | +| Field | Type | Example | Description | | ||||
| 1897 | +| :- | :- | :- | :- | | ||||
| 1898 | +| `query` | string | `"react hooks best practices"` | Search query | | ||||
| 1899 | +| `allowed_domains` | array | `["docs.example.com"]` | Optional: only include results from these domains | | ||||
| 1900 | +| `blocked_domains` | array | `["spam.example.com"]` | Optional: exclude results from these domains | | ||||
| 1901 | +| `mode` | string | `"extended"` | Optional: search type. `"standard"` requests a lighter search and `"extended"` the full search. Some sessions don't send `mode`, and a call without it runs the full search. Requires Claude Code v2.1.282 or later | | ||||
| 1902 | + | ||||
| 1903 | +##### Agent | ||||
| 1904 | + | ||||
| 1905 | +Spawns a [subagent](https://code.claude.com/docs/en/sub-agents.md). | ||||
| 1906 | + | ||||
| 1907 | +| Field | Type | Example | Description | | ||||
| 1908 | +| :- | :- | :- | :- | | ||||
| 1909 | +| `prompt` | string | `"Find all API endpoints"` | The task for the agent to perform | | ||||
| 1910 | +| `description` | string | `"Find API endpoints"` | Short description of the task | | ||||
| 1911 | +| `subagent_type` | string | `"Explore"` | Type of specialized agent to use | | ||||
| 1912 | +| `model` | string | `"sonnet"` | Optional model alias to override the default | | ||||
| 1913 | + | ||||
| 1914 | +When a foreground Agent call completes, your [PostToolUse hook](#posttooluse) receives the subagent's result and run telemetry in `tool_response`. Read these fields to inspect the run; for token and cost rollups across subagents, use the [token and cost counters](https://code.claude.com/docs/en/monitoring-usage.md#token-counter) filtered to `query_source` `"subagent"`, since `totalTokens` and `usage` cover the final request only: | ||||
| 1915 | + | ||||
| 1916 | +| Field | Type | Example | Description | | ||||
| 1917 | +| :- | :- | :- | :- | | ||||
| 1918 | +| `status` | string | `"completed"` | `"completed"` for foreground subagents, `"async_launched"` for background subagents. For which subagents run each way, see [Run subagents in foreground or background](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) | | ||||
| 1919 | +| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identifier for the subagent run | | ||||
| 1920 | +| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | The subagent's final text blocks, or, for a subagent whose report goes through `SubagentHandback`, a short note about that hand-back in their place | | ||||
| 1921 | +| `resolvedModel` | string | `"claude-sonnet-4-5"` | Model the subagent started on, which may differ from the requested model | | ||||
| 1922 | +| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Models used in order, with consecutive repeats collapsed; set only when the model was swapped mid-run | | ||||
| 1923 | +| `totalTokens` | number | `12450` | Token count from the subagent's final API request: input, output, and cache tokens combined. This isn't a total across the whole run | | ||||
| 1924 | +| `totalDurationMs` | number | `48211` | Wall-clock duration of the subagent run | | ||||
| 1925 | +| `totalToolUseCount` | number | `7` | Count of tool calls the subagent made | | ||||
| 1926 | +| `usage` | object | `{"input_tokens": 8320, ...}` | Per-type token breakdown of the final API request: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` | | ||||
| 1927 | + | ||||
| 1928 | +On Claude Code v2.1.271 or later, a subagent that runs with the [`SubagentHandback`](https://code.claude.com/docs/en/tools-reference) tool, which Claude Code provides in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), delivers its report through that tool rather than returning it as text. The `content` field of its `completed` result then carries a short note about that hand-back rather than the report itself. To read the report, match a `PreToolUse` or `PostToolUse` hook on `SubagentHandback` and read `tool_input.message`. | ||||
| 1929 | + | ||||
| 1930 | +For background subagents, the tool returns when the task moves to the background, so `tool_response` carries no usage fields: a background launch returns immediately, and a foreground task that Claude Code backgrounds mid-run returns at that transition. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`. | ||||
| 1931 | + | ||||
| 1932 | +On a `completed` response, `resolvedModel` names the model the subagent started on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. On an `async_launched` response, `resolvedModel` names the model in use when the agent moved to the background, so a swap that happened before backgrounding is reflected there. | ||||
| 1933 | + | ||||
| 1934 | +##### AskUserQuestion | ||||
| 1935 | + | ||||
| 1936 | +Asks the user one to four multiple-choice questions. | ||||
| 1937 | + | ||||
| 1938 | +| Field | Type | Example | Description | | ||||
| 1939 | +| :- | :- | :- | :- | | ||||
| 1940 | +| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | Questions to present, each with a `question` string, short `header`, `options` array, and optional `multiSelect` flag | | ||||
| 1941 | +| `answers` | object | `{"Which framework?": "React"}` | Optional. Maps question text to the selected option label. Multi-select answers join labels with commas. Claude doesn't set this field; supply it via `updatedInput` to answer programmatically | | ||||
| 1942 | + | ||||
| 1943 | +##### ExitPlanMode | ||||
| 1944 | + | ||||
| 1945 | +Presents a plan and asks the user to approve it before Claude leaves [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode). Claude writes the plan to a file on disk before calling the tool, so the literal `tool_input` from the model is typically empty. Claude Code injects the plan content and file path before passing the input to hooks. | ||||
| 1946 | + | ||||
| 1947 | +| Field | Type | Example | Description | | ||||
| 1948 | +| :- | :- | :- | :- | | ||||
| 1949 | +| `plan` | string | `"## Refactor auth\n1. Extract..."` | Plan content in Markdown. Injected from the plan file on disk | | ||||
| 1950 | +| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Path to the plan file. Injected | | ||||
| 1951 | +| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecated. Claude Code accepts the field but ignores it. Before v2.1.205, it carried prompt-based permissions Claude requested to implement the plan | | ||||
| 1952 | + | ||||
| 1953 | +In `PostToolUse`, `tool_response` is an object with `plan` and `filePath` fields holding the approved plan, plus internal status flags. Read `tool_response.plan` for the plan content rather than re-reading the file from disk. | ||||
| 1954 | + | ||||
| 1955 | +#### PreToolUse decision control | ||||
| 1956 | + | ||||
| 1957 | +`PreToolUse` hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level `decision` field, PreToolUse returns its decision inside a `hookSpecificOutput` object. This gives it richer control: four outcomes (allow, deny, ask, or defer) plus the ability to modify tool input before execution. | ||||
| 1958 | + | ||||
| 1959 | +| Field | Description | | ||||
| 1960 | +| :- | :- | | ||||
| 1961 | +| `permissionDecision` | `"allow"` skips the permission prompt, except for [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) and [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths). It doesn't skip approval for calls to [tools an Agent SDK app marks `always_ask`](https://code.claude.com/docs/en/agent-sdk/custom-tools#require-approval-for-specific-tools) either, unless the [permission mode approves the call](https://code.claude.com/docs/en/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call). `AskUserQuestion` and `ExitPlanMode` need [`updatedInput` paired with `"allow"`](#allow-with-updatedinput). For plan mode, see [Hook approvals in plan mode](https://code.claude.com/docs/en/permissions.md#hook-approvals-in-plan-mode). `"deny"` prevents the tool call. `"ask"` prompts the user to confirm. `"defer"` ends the turn so the tool can be resumed later, and requires [non-interactive mode](#defer-a-tool-call-for-later) with the `-p` flag. [Deny and ask rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) are still evaluated regardless of what the hook returns | | ||||
| 1962 | +| `permissionDecisionReason` | For `"ask"`, shown to the user in the permission prompt. When Claude Code [denies the call](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs) in a `-p` run where no one can answer that prompt, Claude reads the reason in the tool result instead. For `"deny"`, shown to Claude. For `"allow"` and `"defer"`, written to the [debug log](#debug-hooks) only | | ||||
| 1963 | +| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Claude Code evaluates permission rules and a Bash command's [auto-background eligibility](https://code.claude.com/docs/en/tools-reference.md#foreground-commands-that-move-to-the-background) against the input your hook returns, not the input Claude sent. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored | | ||||
| 1964 | +| `additionalContext` | String added to Claude's context alongside the tool result. Ignored when `permissionDecision` is `"defer"`. See [Add context for Claude](#add-context-for-claude) | | ||||
| 1965 | + | ||||
| 1966 | +When multiple PreToolUse hooks return different decisions, precedence is `deny` > `defer` > `ask` > `allow`. | ||||
| 1967 | + | ||||
| 1968 | +A hook that blocks by exiting 2 routes the same way as `"deny"`: Claude sees the stderr message as the denial reason. | ||||
| 1969 | + | ||||
| 1970 | +When a hook returns `"ask"`, the permission prompt displayed to the user includes a label identifying where the hook came from: `[settings]` for a hook from any settings file or from agent frontmatter, `[plugin:<name>]` for a plugin's hook, or `[skill]` for a hook from skill frontmatter. This helps users understand which configuration source is requesting confirmation. | ||||
| 1971 | + | ||||
| 1972 | +```json theme={null} | ||||
| 1973 | +{ | ||||
| 1974 | + "hookSpecificOutput": { | ||||
| 1975 | + "hookEventName": "PreToolUse", | ||||
| 1976 | + "permissionDecision": "allow", | ||||
| 1977 | + "permissionDecisionReason": "My reason here", | ||||
| 1978 | + "updatedInput": { | ||||
| 1979 | + "field_to_modify": "new value" | ||||
| 1980 | + }, | ||||
| 1981 | + "additionalContext": "Current environment: production. Proceed with caution." | ||||
| 1982 | + } | ||||
| 1983 | +} | ||||
| 1984 | +``` | ||||
| 1985 | + | ||||
| 1986 | +> [!NOTE] | ||||
| 1987 | +> | ||||
| 1988 | +> PreToolUse previously used top-level `decision` and `reason` fields, but these are deprecated for this event. Use `hookSpecificOutput.permissionDecision` and `hookSpecificOutput.permissionDecisionReason` instead. The deprecated values `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively. Other events like PostToolUse and Stop continue to use top-level `decision` and `reason` as their current format. | ||||
| 1989 | + | ||||
| 1990 | +#### PreToolUse `ask` decisions in auto mode | ||||
| 1991 | + | ||||
| 1992 | +In [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), a PreToolUse hook's `"ask"` normally sends the tool call to the permission prompt, and the [classifier](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions) doesn't decide it. Some calls take a different path: | ||||
| 1993 | + | ||||
| 1994 | +* **Calls that Claude Code's own checks flag too**: these include writes to [protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths) and commands that ask to [run outside the sandbox](https://code.claude.com/docs/en/sandboxing.md#the-unsandboxed-retry-escape-hatch). The classifier can deny one of these calls before any prompt appears. If it approves, the call normally still goes to the prompt. | ||||
| 1995 | +* **`SubagentHandback` calls**: this tool delivers a subagent's report. No prompt appears for it, and the call runs even if the classifier objects. | ||||
| 1996 | + | ||||
| 1997 | +To stop a `SubagentHandback` call, return `"deny"`. Claude Code then tells the subagent, up to three times, that its report wasn't delivered and to call the tool again. If your hook keeps denying, the subagent ends without delivering a report through this tool, and the conversation waiting on it gets a note saying so. | ||||
| 1998 | + | ||||
| 1999 | +#### Tools that require user interaction | ||||
| 2000 | + | ||||
| 2001 | +`AskUserQuestion` and `ExitPlanMode` require user interaction. In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, Claude Code offers them only when the run has a [permission host](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs) to receive the prompt, such as an Agent SDK `canUseTool` callback. | ||||
| 2002 | + | ||||
| 2003 | +A `PreToolUse` hook satisfies that requirement when it does the following: | ||||
| 2004 | + | ||||
| 2005 | +1. Reads the tool's input from stdin | ||||
| 2006 | +2. Collects the answer through your own UI | ||||
| 2007 | +3. Returns `permissionDecision: "allow"` together with `updatedInput` that holds the answer, so the tool runs without prompting | ||||
| 2008 | + | ||||
| 2009 | +Returning `"allow"` alone is not sufficient for these tools. | ||||
| 2010 | + | ||||
| 2011 | +For `AskUserQuestion`, echo back the original `questions` array and add an [`answers`](#askuserquestion) object mapping each question's text to the chosen answer. This output answers one question with `React`: | ||||
| 2012 | + | ||||
| 2013 | +```json theme={null} | ||||
| 2014 | +{ | ||||
| 2015 | + "hookSpecificOutput": { | ||||
| 2016 | + "hookEventName": "PreToolUse", | ||||
| 2017 | + "permissionDecision": "allow", | ||||
| 2018 | + "updatedInput": { | ||||
| 2019 | + "questions": [ | ||||
| 2020 | + { | ||||
| 2021 | + "question": "Which framework?", | ||||
| 2022 | + "header": "Framework", | ||||
| 2023 | + "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], | ||||
| 2024 | + "multiSelect": false | ||||
| 2025 | + } | ||||
| 2026 | + ], | ||||
| 2027 | + "answers": {"Which framework?": "React"} | ||||
| 2028 | + } | ||||
| 2029 | + } | ||||
| 2030 | +} | ||||
| 2031 | +``` | ||||
| 2032 | + | ||||
| 2033 | +An MCP tool whose server marks it with [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) is stricter: a hook can't skip its approval prompt with `"allow"`, with or without `updatedInput`, because Claude Code can't confirm the hook collected the interaction the tool needs. | ||||
| 2034 | + | ||||
| 2035 | +#### Defer a tool call for later | ||||
| 2036 | + | ||||
| 2037 | +`"defer"` is for integrations that run `claude -p` as a subprocess and read its JSON output, such as an Agent SDK app or a custom UI built on top of Claude Code. It lets that calling process pause Claude at a tool call, collect input through its own interface, and resume where it left off. Claude Code honors this value only in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. In interactive sessions it logs a warning and ignores the hook result. | ||||
| 2038 | + | ||||
| 2039 | +The `AskUserQuestion` tool is the typical case: Claude wants to ask the user something, but there is no terminal to answer in. A `-p` run offers `AskUserQuestion` only when it has a [permission host](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs), such as an MCP tool you pass with `--permission-prompt-tool`, so start the run with one. The round trip works like this: | ||||
| 2040 | + | ||||
| 2041 | +1. Claude calls `AskUserQuestion`. The `PreToolUse` hook fires. | ||||
| 2042 | +2. The hook returns `permissionDecision: "defer"`. The tool doesn't execute. The turn ends with a result carrying `stop_reason: "tool_deferred"`, and the pending tool call stays in the transcript. | ||||
| 2043 | +3. The calling process reads `deferred_tool_use` from the SDK result, surfaces the question in its own UI, and waits for an answer. | ||||
| 2044 | +4. The calling process runs `claude -p --resume <session-id>` with the same permission host. The same tool call fires `PreToolUse` again. | ||||
| 2045 | +5. The hook returns `permissionDecision: "allow"` with the answer in `updatedInput`. The tool executes and Claude continues. | ||||
| 2046 | + | ||||
| 2047 | +The `deferred_tool_use` field carries the tool's `id`, `name`, and `input`. The `input` is the parameters Claude generated for the tool call, captured before execution: | ||||
| 2048 | + | ||||
| 2049 | +```json theme={null} | ||||
| 2050 | +{ | ||||
| 2051 | + "type": "result", | ||||
| 2052 | + "subtype": "success", | ||||
| 2053 | + "stop_reason": "tool_deferred", | ||||
| 2054 | + "session_id": "abc123", | ||||
| 2055 | + "deferred_tool_use": { | ||||
| 2056 | + "id": "toolu_01abc", | ||||
| 2057 | + "name": "AskUserQuestion", | ||||
| 2058 | + "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false }] } | ||||
| 2059 | + } | ||||
| 2060 | +} | ||||
| 2061 | +``` | ||||
| 2062 | + | ||||
| 2063 | +There is no timeout or retry limit. The session remains on disk until you resume it, subject to the [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) retention sweep, which deletes session files after 30 days by default, following the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically). | ||||
| 2064 | + | ||||
| 2065 | +If the deferred tool is no longer available when you resume, the resume's first result has `stop_reason: "tool_deferred_unavailable"` and `is_error: true`, and the hook doesn't fire. This happens when an MCP server that provided the tool is not connected for the resumed session. The `deferred_tool_use` payload is still included so you can identify which tool went missing. | ||||
| 2066 | + | ||||
| 2067 | +* **If you sent no prompt, with the resume or after it**, the call is still pending. Resume again with the tool available and it runs first. | ||||
| 2068 | +* **If you sent a prompt, with the resume or after it**, Claude Code answers it without the tool's result and drops the deferred call. Send a new prompt once the tool is available if you still need it called. | ||||
| 2069 | + | ||||
| 2070 | +If the answer you're waiting for is not ready when you resume without a prompt, the hook can return `"defer"` again. If you sent a prompt and the hook defers again, Claude Code treats the prompt the same way: it answers without the tool's result and drops the call. Resume without a prompt until the hook returns `"allow"` or `"deny"`, which is how the calling process breaks the loop. | ||||
| 2071 | + | ||||
| 2072 | +`"defer"` only works when Claude makes a single tool call in the turn. If Claude makes several tool calls at once, `"defer"` is ignored with a warning and the tool proceeds through the normal permission flow. The constraint exists because resume can only re-run one tool: there is no way to defer one call from a batch without leaving the others unresolved. | ||||
| 2073 | + | ||||
| 2074 | +> [!NOTE] | ||||
| 2075 | +> | ||||
| 2076 | +> To resume a deferred session in plan mode, pass [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags) along with `--resume` so that Claude Code can present the plan for approval. For the other conditions, see [Resume in plan mode with `-p`](https://code.claude.com/docs/en/sessions#resume-in-plan-mode-with-p). Requires Claude Code v2.1.246 or later. | ||||
| 2077 | +> | ||||
| 2078 | +> When you resume with `-p`, Claude Code doesn't restore any other stored permission mode. It starts the run in the permission mode a new `claude -p` run would start in, so pass `--permission-mode` or `--dangerously-skip-permissions` again if the deferred session used one. When you resume with `claude --resume <session-id>` without `-p`, Claude Code restores the stored permission mode, with the exceptions listed in [permission mode on resume](https://code.claude.com/docs/en/sessions.md#permission-mode-on-resume). | ||||
| 2079 | + | ||||
| 2080 | +### PermissionRequest | ||||
| 2081 | + | ||||
| 2082 | +Runs when Claude Code is about to ask you for permission to use a tool. In sessions that can't show a prompt, such as background subagents in [non-interactive mode](https://code.claude.com/docs/en/headless.md), Claude Code still runs these hooks, and if no hook returns a decision, it denies the tool call. For a call that reaches a `--permission-prompt-tool` or the Agent SDK's [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/permissions), the hooks run alongside your host, and whichever decides first applies. | ||||
| 2083 | +Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user. | ||||
| 2084 | + | ||||
| 2085 | +Use this event when you need a signal the moment Claude asks for permission to use a tool. Claude Code runs a [Notification](#notification) hook with the `permission_prompt` type only after the prompt has waited about six seconds. | ||||
| 2086 | + | ||||
| 2087 | +Claude Code doesn't run PermissionRequest hooks for a sandboxed command's [network request](https://code.claude.com/docs/en/sandboxing.md#network-isolation). To get a signal for that prompt, use the `permission_prompt` notification type. | ||||
| 2088 | + | ||||
| 2089 | +Matches on tool name, same values as PreToolUse. | ||||
| 2090 | + | ||||
| 2091 | +#### PermissionRequest input | ||||
| 2092 | + | ||||
| 2093 | +PermissionRequest hooks receive `tool_name` and `tool_input` fields like PreToolUse hooks, but without `tool_use_id`. For an MCP tool, they also receive the [`mcp_server`](#pretooluse-input) object. An optional `permission_suggestions` array contains the [permission updates](#permission-update-entries) Claude Code suggests for this request, such as adding an allow rule or changing the permission mode. | ||||
| 2094 | + | ||||
| 2095 | +The `permission_suggestions` array isn't an exact list of the options you see, because each permission dialog builds its own options. Some dialogs, such as the one for file edits, don't read the array at all and derive their options from the request itself. A dialog that does read it can still withhold an option whose suggestion stays in the array, for example when [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedpermissionrulesonly) hides rule-saving options. It can also offer options that have no suggestion entry, such as [**Yes, and switch to auto mode**](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes), which changes the permission mode directly rather than through a permission update. | ||||
| 2096 | + | ||||
| 2097 | +PreToolUse hooks run before every tool call, whether or not it needs permission. PermissionRequest hooks run only when Claude Code is about to ask you for permission, or when it would otherwise auto-deny a call that can't prompt. Neither event fires for [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior). | ||||
| 2098 | + | ||||
| 2099 | +```json theme={null} | ||||
| 2100 | +{ | ||||
| 2101 | + "session_id": "abc123", | ||||
| 2102 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2103 | + "cwd": "/Users/...", | ||||
| 2104 | + "permission_mode": "default", | ||||
| 2105 | + "hook_event_name": "PermissionRequest", | ||||
| 2106 | + "tool_name": "Bash", | ||||
| 2107 | + "tool_input": { | ||||
| 2108 | + "command": "rm -rf node_modules", | ||||
| 2109 | + "description": "Remove node_modules directory" | ||||
| 2110 | + }, | ||||
| 2111 | + "permission_suggestions": [ | ||||
| 2112 | + { | ||||
| 2113 | + "type": "addRules", | ||||
| 2114 | + "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }], | ||||
| 2115 | + "behavior": "allow", | ||||
| 2116 | + "destination": "localSettings" | ||||
| 2117 | + } | ||||
| 2118 | + ] | ||||
| 2119 | +} | ||||
| 2120 | +``` | ||||
| 2121 | + | ||||
| 2122 | +#### PermissionRequest decision control | ||||
| 2123 | + | ||||
| 2124 | +`PermissionRequest` hooks can allow or deny permission requests. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return a `decision` object with these event-specific fields: | ||||
| 2125 | + | ||||
| 2126 | +| Field | Description | | ||||
| 2127 | +| :- | :- | | ||||
| 2128 | +| `behavior` | `"allow"` grants the permission, `"deny"` denies it. [Deny and ask rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) are still evaluated, so a hook returning `"allow"` doesn't override a matching deny rule | | ||||
| 2129 | +| `updatedInput` | For `"allow"` only: modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. The modified input is re-evaluated against deny and ask rules | | ||||
| 2130 | +| `updatedPermissions` | For `"allow"` only: array of [permission update entries](#permission-update-entries) to apply, such as adding an allow rule or changing the session permission mode | | ||||
| 2131 | +| `message` | For `"deny"` only: tells Claude why the permission was denied | | ||||
| 2132 | +| `interrupt` | For `"deny"` only: if `true`, stops Claude | | ||||
| 2133 | + | ||||
| 2134 | +A hook that exits 2 without a `decision` object leaves the permission flow unchanged, and its stderr is discarded. To grant or deny the request, return the `decision` object. | ||||
| 2135 | + | ||||
| 2136 | +```json theme={null} | ||||
| 2137 | +{ | ||||
| 2138 | + "hookSpecificOutput": { | ||||
| 2139 | + "hookEventName": "PermissionRequest", | ||||
| 2140 | + "decision": { | ||||
| 2141 | + "behavior": "allow", | ||||
| 2142 | + "updatedInput": { | ||||
| 2143 | + "command": "npm run lint" | ||||
| 2144 | + } | ||||
| 2145 | + } | ||||
| 2146 | + } | ||||
| 2147 | +} | ||||
| 2148 | +``` | ||||
| 2149 | + | ||||
| 2150 | +#### Permission update entries | ||||
| 2151 | + | ||||
| 2152 | +The `updatedPermissions` output field and the [`permission_suggestions` input field](#permissionrequest-input) both use the same array of entry objects. Each entry has a `type` that determines its other fields, and a `destination` that controls where the change is written. | ||||
| 2153 | + | ||||
| 2154 | +| `type` | Fields | Effect | | ||||
| 2155 | +| :- | :- | :- | | ||||
| 2156 | +| `addRules` | `rules`, `behavior`, `destination` | Adds permission rules. `rules` is an array of `{toolName, ruleContent?}` objects. Omit `ruleContent` to match the whole tool. `behavior` is `"allow"`, `"deny"`, or `"ask"` | | ||||
| 2157 | +| `replaceRules` | `rules`, `behavior`, `destination` | Replaces all rules of the given `behavior` at the `destination` with the provided `rules` | | ||||
| 2158 | +| `removeRules` | `rules`, `behavior`, `destination` | Removes matching rules of the given `behavior` | | ||||
| 2159 | +| `setMode` | `mode`, `destination` | Changes the permission mode. Valid modes are `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, and `manual` as an alias for `default` | | ||||
| 2160 | +| `addDirectories` | `directories`, `destination` | Adds working directories. `directories` is an array of path strings | | ||||
| 2161 | +| `removeDirectories` | `directories`, `destination` | Removes working directories | | ||||
| 2162 | + | ||||
| 2163 | +> [!NOTE] | ||||
| 2164 | +> | ||||
| 2165 | +> `setMode` with `bypassPermissions` only takes effect if you launched the session with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode). Otherwise the update is a no-op. The update is also a no-op when [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/en/permissions#managed-settings) disables the mode, or when the session starts in [restricted mode](https://code.claude.com/docs/en/cli-reference.md#cli-flags). | ||||
| 2166 | +> | ||||
| 2167 | +> `bypassPermissions` is never persisted as `defaultMode` regardless of `destination`. | ||||
| 2168 | + | ||||
| 2169 | +The `destination` field on every entry determines whether the change stays in memory or persists to a settings file. | ||||
| 2170 | + | ||||
| 2171 | +| `destination` | Writes to | | ||||
| 2172 | +| :- | :- | | ||||
| 2173 | +| `session` | in-memory only, discarded when the session ends | | ||||
| 2174 | +| `localSettings` | `.claude/settings.local.json` | | ||||
| 2175 | +| `projectSettings` | `.claude/settings.json` | | ||||
| 2176 | +| `userSettings` | `~/.claude/settings.json` | | ||||
| 2177 | + | ||||
| 2178 | +A hook can echo one of the `permission_suggestions` it received as its own `updatedPermissions` output. | ||||
| 2179 | + | ||||
| 2180 | +### PostToolUse | ||||
| 2181 | + | ||||
| 2182 | +Runs immediately after a tool completes successfully. | ||||
| 2183 | + | ||||
| 2184 | +Matches on tool name, same values as PreToolUse. | ||||
| 2185 | + | ||||
| 2186 | +Match more broadly when the tool name isn't the right filter: | ||||
| 2187 | + | ||||
| 2188 | +* To run a hook after any tool completes successfully, omit the `matcher` or set it to `"*"`. Your hook can then discover what changed itself, for example by running `git status --porcelain`, which also lists untracked files that `git diff` misses. For tool calls that fail, add the same hook under [PostToolUseFailure](#posttoolusefailure). | ||||
| 2189 | +* To run a hook when a specific file changes on disk, whatever wrote it, use [FileChanged](#filechanged). Claude Code doesn't run a `PostToolUse` hook matching `Edit|Write` when a `Bash` command or a process outside Claude Code rewrites the same file. | ||||
| 2190 | + | ||||
| 2191 | +#### PostToolUse input | ||||
| 2192 | + | ||||
| 2193 | +`PostToolUse` hooks fire after a tool has already executed successfully. The input includes both `tool_input`, the arguments sent to the tool, and `tool_response`, the result it returned. The exact schema for both depends on the tool. File-tool `tool_input` paths arrive in the same format as for [PreToolUse](#pretooluse-input): always absolute, with the platform's native separators, so backslashes on Windows. For an MCP tool, the input also carries the [`mcp_server`](#pretooluse-input) object. | ||||
| 2194 | + | ||||
| 2195 | +```json theme={null} | ||||
| 2196 | +{ | ||||
| 2197 | + "session_id": "abc123", | ||||
| 2198 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2199 | + "cwd": "/Users/...", | ||||
| 2200 | + "permission_mode": "default", | ||||
| 2201 | + "hook_event_name": "PostToolUse", | ||||
| 2202 | + "tool_name": "Write", | ||||
| 2203 | + "tool_input": { | ||||
| 2204 | + "file_path": "/path/to/file.txt", | ||||
| 2205 | + "content": "file content" | ||||
| 2206 | + }, | ||||
| 2207 | + "tool_response": { | ||||
| 2208 | + "filePath": "/path/to/file.txt", | ||||
| 2209 | + "type": "create" | ||||
| 2210 | + }, | ||||
| 2211 | + "tool_use_id": "toolu_01ABC123...", | ||||
| 2212 | + "duration_ms": 12 | ||||
| 2213 | +} | ||||
| 2214 | +``` | ||||
| 2215 | + | ||||
| 2216 | +| Field | Description | | ||||
| 2217 | +| :- | :- | | ||||
| 2218 | +| `duration_ms` | Optional. Tool execution time in milliseconds. Excludes time spent in permission prompts and PreToolUse hooks | | ||||
| 2219 | + | ||||
| 2220 | +#### PostToolUse decision control | ||||
| 2221 | + | ||||
| 2222 | +`PostToolUse` hooks can provide feedback to Claude after tool execution. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return these event-specific fields: | ||||
| 2223 | + | ||||
| 2224 | +| Field | Description | | ||||
| 2225 | +| :- | :- | | ||||
| 2226 | +| `decision` | `"block"` adds the `reason` next to the tool result. Claude still sees the original output; to replace it, use `updatedToolOutput` | | ||||
| 2227 | +| `reason` | Explanation shown to Claude when `decision` is `"block"` | | ||||
| 2228 | +| `additionalContext` | String added to Claude's context alongside the tool result. See [Add context for Claude](#add-context-for-claude) | | ||||
| 2229 | +| `classifierContext` | Short note about this call's result for the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than for Claude. See [Annotate a result for the auto mode classifier](#annotate-a-result-for-the-auto-mode-classifier). Requires Claude Code v2.1.236 or later | | ||||
| 2230 | +| `updatedToolOutput` | Replaces the tool's output with the provided value before it is sent to Claude. The value must match the tool's output shape | | ||||
| 2231 | +| `updatedMCPToolOutput` | Replaces the output for [MCP tools](#match-mcp-tools) only. Prefer `updatedToolOutput`, which works for all tools | | ||||
| 2232 | + | ||||
| 2233 | +The example below replaces the output of a `Bash` call. The replacement value matches the `Bash` tool's output shape: | ||||
| 2234 | + | ||||
| 2235 | +```json theme={null} | ||||
| 2236 | +{ | ||||
| 2237 | + "hookSpecificOutput": { | ||||
| 2238 | + "hookEventName": "PostToolUse", | ||||
| 2239 | + "additionalContext": "Additional information for Claude", | ||||
| 2240 | + "updatedToolOutput": { | ||||
| 2241 | + "stdout": "[redacted]", | ||||
| 2242 | + "stderr": "", | ||||
| 2243 | + "interrupted": false, | ||||
| 2244 | + "isImage": false | ||||
| 2245 | + } | ||||
| 2246 | + } | ||||
| 2247 | +} | ||||
| 2248 | +``` | ||||
| 2249 | + | ||||
| 2250 | +> [!WARNING] | ||||
| 2251 | +> | ||||
| 2252 | +> `updatedToolOutput` only changes what Claude sees. The tool has already run by the time the hook fires, so any files written, commands executed, or network requests sent have already taken effect. Telemetry such as OpenTelemetry tool spans and analytics events also captures the original output before the hook runs. To prevent or modify a tool call before it runs, use a [PreToolUse](#pretooluse) hook instead. | ||||
| 2253 | +> | ||||
| 2254 | +> The replacement value must match the tool's output shape. Built-in tools return structured objects rather than plain strings. For example, `Bash` returns an object with `stdout`, `stderr`, `interrupted`, and `isImage` fields. For built-in tools, a value that doesn't match the tool's output schema is ignored and the original output is used. MCP tool output is passed through without schema validation. Stripping error details that Claude needs can cause it to proceed on a false assumption. | ||||
| 2255 | + | ||||
| 2256 | +#### Annotate a result for the auto mode classifier | ||||
| 2257 | + | ||||
| 2258 | +Return `classifierContext` to send a short note about the tool call's result to the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than to Claude. The classifier [never receives tool results themselves](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions), so this field is the supported way to tell it something about what a call returned before it reviews later actions. The field requires Claude Code v2.1.236 or later. | ||||
| 2259 | + | ||||
| 2260 | +The example below tells the classifier where a query's output came from: | ||||
| 2261 | + | ||||
| 2262 | +```json theme={null} | ||||
| 2263 | +{ | ||||
| 2264 | + "hookSpecificOutput": { | ||||
| 2265 | + "hookEventName": "PostToolUse", | ||||
| 2266 | + "classifierContext": "This query ran against the staging database, not production." | ||||
| 2267 | + } | ||||
| 2268 | +} | ||||
| 2269 | +``` | ||||
| 2270 | + | ||||
| 2271 | +How much weight the classifier gives the note depends on where you configured the hook: | ||||
| 2272 | + | ||||
| 2273 | +* **Hooks configured in Claude Code**: for hooks from settings files, plugins, skills, and agent frontmatter, the classifier treats the note as unverified, application-provided context. The note never establishes user intent, and if it claims you approved or requested something, the classifier checks that claim against your own messages in the conversation | ||||
| 2274 | +* **In-process Agent SDK callbacks**: when an application embedding Claude Code registers the hook as a [TypeScript SDK callback](https://code.claude.com/docs/en/agent-sdk/hooks.md) and returns the note during the live session, the classifier may weigh a user statement relayed in the note as user intent. Such a statement can satisfy a consent requirement the classifier would accept from a message you send, but it never lifts a block that your own message couldn't lift either. After a session resumes, Claude Code treats restored notes as unverified context. When hooks from both groups annotate the same call, the classifier treats the combined note as unverified | ||||
| 2275 | + | ||||
| 2276 | +Claude Code applies these limits when delivering the note: | ||||
| 2277 | + | ||||
| 2278 | +* **Length**: Claude Code caps the notes for one tool call at 2,000 characters and truncates the rest. The cap is shared across every hook that responds to that call | ||||
| 2279 | +* **Synchronous responses only**: Claude Code ignores the field in the response of a hook that [runs in the background](#run-hooks-in-the-background), because that response arrives after Claude Code records the tool result | ||||
| 2280 | +* **Calls that the classifier doesn't record**: the classifier's transcript omits read-only lookups such as file reads and searches. Claude Code discards a note attached to one of those calls | ||||
| 2281 | +* **Interaction with rewrites**: when the note describes output you're replacing with `updatedToolOutput`, return both fields in the same hook response. Claude Code drops the note if that rewrite is rejected or another hook's rewrite replaces it. Claude Code delivers a note you return without a rewrite even when another hook rewrites the output | ||||
| 2282 | + | ||||
| 2283 | +> [!WARNING] | ||||
| 2284 | +> | ||||
| 2285 | +> The classifier reads content you place in `classifierContext` as information from the application hosting the session, so don't copy untrusted tool output or third-party text into it. Keep the note to a short assertion about this one call, such as a fact about its origin or a user statement about it; don't use the field to deliver unrelated messages or a stream of events. | ||||
| 2286 | + | ||||
| 2287 | +### PostToolUseFailure | ||||
| 2288 | + | ||||
| 2289 | +Runs when a tool that started executing fails: the tool threw an error, or an MCP tool returned an error result. Use this to log failures, send alerts, or provide corrective feedback to Claude. | ||||
| 2290 | + | ||||
| 2291 | +Matches on tool name, same values as PreToolUse. | ||||
| 2292 | + | ||||
| 2293 | +> [!NOTE] | ||||
| 2294 | +> | ||||
| 2295 | +> This event doesn't fire for tool calls rejected before execution: an unknown tool name, input that fails schema or tool-specific validation, or a permission denial. Validation rejections are returned as `tool_use_error` results and happen before hooks run, so they fire neither `PreToolUse` nor `PostToolUseFailure`. Permission denials fire `PreToolUse` but not this event; see [PermissionDenied](#permissiondenied). | ||||
| 2296 | + | ||||
| 2297 | +#### PostToolUseFailure input | ||||
| 2298 | + | ||||
| 2299 | +PostToolUseFailure hooks receive the same `tool_name` and `tool_input` fields as PostToolUse, along with error information as top-level fields. For an MCP tool, they also receive the [`mcp_server`](#pretooluse-input) object. For example, a failed `npm test` command might deliver: | ||||
| 2300 | + | ||||
| 2301 | +```json theme={null} | ||||
| 2302 | +{ | ||||
| 2303 | + "session_id": "abc123", | ||||
| 2304 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2305 | + "cwd": "/Users/...", | ||||
| 2306 | + "permission_mode": "default", | ||||
| 2307 | + "hook_event_name": "PostToolUseFailure", | ||||
| 2308 | + "tool_name": "Bash", | ||||
| 2309 | + "tool_input": { | ||||
| 2310 | + "command": "npm test", | ||||
| 2311 | + "description": "Run test suite" | ||||
| 2312 | + }, | ||||
| 2313 | + "tool_use_id": "toolu_01ABC123...", | ||||
| 2314 | + "error": "Exit code 1\nError: Cannot find module 'express'", | ||||
| 2315 | + "is_interrupt": false, | ||||
| 2316 | + "duration_ms": 4187 | ||||
| 2317 | +} | ||||
| 2318 | +``` | ||||
| 2319 | + | ||||
| 2320 | +| Field | Description | | ||||
| 2321 | +| :- | :- | | ||||
| 2322 | +| `error` | String describing what went wrong. The format depends on the tool that failed | | ||||
| 2323 | +| `is_interrupt` | Optional boolean. True when the failure reached Claude Code as an abort rather than as an error the tool reported. Cancelling a running tool does not fire this hook; the tool result carries the interruption message instead | | ||||
| 2324 | +| `duration_ms` | Optional. Tool execution time in milliseconds. Excludes time spent in permission prompts and PreToolUse hooks | | ||||
| 2325 | + | ||||
| 2326 | +The `error` string is generally the same text Claude receives as the failed tool's result. Its format varies by tool and failure. Key your hook on `tool_name`, `is_interrupt`, and the `Exit code N` first line; treat the rest of the string as display text, not a stable format. | ||||
| 2327 | + | ||||
| 2328 | +* For Bash and PowerShell, a command that ran and exited produces a first line `Exit code N`, then any output the command produced as one block with stdout and stderr interleaved | ||||
| 2329 | +* A payload may also carry a bare failure message with no exit-code line, when Claude Code could not start the shell process itself | ||||
| 2330 | +* Claude Code middle-truncates long strings around a `... [N characters truncated] ...` marker, and can insert lines of its own, such as `Command timed out after 2m 0s` | ||||
| 2331 | + | ||||
| 2332 | +#### PostToolUseFailure decision control | ||||
| 2333 | + | ||||
| 2334 | +`PostToolUseFailure` hooks can provide context to Claude after a tool failure. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return these event-specific fields: | ||||
| 2335 | + | ||||
| 2336 | +| Field | Description | | ||||
| 2337 | +| :- | :- | | ||||
| 2338 | +| `additionalContext` | String added to Claude's context alongside the error. See [Add context for Claude](#add-context-for-claude) | | ||||
| 2339 | + | ||||
| 2340 | +```json theme={null} | ||||
| 2341 | +{ | ||||
| 2342 | + "hookSpecificOutput": { | ||||
| 2343 | + "hookEventName": "PostToolUseFailure", | ||||
| 2344 | + "additionalContext": "Additional information about the failure for Claude" | ||||
| 2345 | + } | ||||
| 2346 | +} | ||||
| 2347 | +``` | ||||
| 2348 | + | ||||
| 2349 | +### PostToolBatch | ||||
| 2350 | + | ||||
| 2351 | +Runs once after every tool call in a batch has resolved, before Claude Code sends the next request to the model. `PostToolUse` fires once per tool, which means it fires concurrently when Claude makes parallel tool calls. `PostToolBatch` fires exactly once with the full batch, so it is the right place to inject context that depends on the set of tools that ran rather than on any single tool. There is no matcher for this event. | ||||
| 2352 | + | ||||
| 2353 | +#### PostToolBatch input | ||||
| 2354 | + | ||||
| 2355 | +In addition to the [common input fields](#common-input-fields), PostToolBatch hooks receive `tool_calls`, an array describing every tool call in the batch: | ||||
| 2356 | + | ||||
| 2357 | +```json theme={null} | ||||
| 2358 | +{ | ||||
| 2359 | + "session_id": "abc123", | ||||
| 2360 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2361 | + "cwd": "/Users/...", | ||||
| 2362 | + "permission_mode": "default", | ||||
| 2363 | + "hook_event_name": "PostToolBatch", | ||||
| 2364 | + "tool_calls": [ | ||||
| 2365 | + { | ||||
| 2366 | + "tool_name": "Read", | ||||
| 2367 | + "tool_input": {"file_path": "/.../ledger/accounts.py"}, | ||||
| 2368 | + "tool_use_id": "toolu_01...", | ||||
| 2369 | + "tool_response": "1\tfrom __future__ import annotations\n2\t..." | ||||
| 2370 | + }, | ||||
| 2371 | + { | ||||
| 2372 | + "tool_name": "Read", | ||||
| 2373 | + "tool_input": {"file_path": "/.../ledger/transactions.py"}, | ||||
| 2374 | + "tool_use_id": "toolu_02...", | ||||
| 2375 | + "tool_response": "1\tfrom __future__ import annotations\n2\t..." | ||||
| 2376 | + } | ||||
| 2377 | + ] | ||||
| 2378 | +} | ||||
| 2379 | +``` | ||||
| 2380 | + | ||||
| 2381 | +`tool_response` contains the same content the model receives in the corresponding `tool_result` block. The value is a serialized string or content-block array, exactly as the tool emitted it. For `Read`, that means line-number-prefixed text rather than raw file contents. Responses can be large, so parse only the fields you need. | ||||
| 2382 | + | ||||
| 2383 | +> [!NOTE] | ||||
| 2384 | +> | ||||
| 2385 | +> The `tool_response` shape differs from `PostToolUse`'s. `PostToolUse` passes the tool's structured `Output` object, such as `{filePath: "...", type: "create"}` for `Write`; `PostToolBatch` passes the serialized `tool_result` content the model sees. | ||||
| 2386 | + | ||||
| 2387 | +#### PostToolBatch decision control | ||||
| 2388 | + | ||||
| 2389 | +`PostToolBatch` hooks can inject context for Claude. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return these event-specific fields: | ||||
| 2390 | + | ||||
| 2391 | +| Field | Description | | ||||
| 2392 | +| :- | :- | | ||||
| 2393 | +| `additionalContext` | Context string injected once before the next model call. See [Add context for Claude](#add-context-for-claude) for delivery details, what to put in it, and how resumed sessions handle past values | | ||||
| 2394 | + | ||||
| 2395 | +```json theme={null} | ||||
| 2396 | +{ | ||||
| 2397 | + "hookSpecificOutput": { | ||||
| 2398 | + "hookEventName": "PostToolBatch", | ||||
| 2399 | + "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete." | ||||
| 2400 | + } | ||||
| 2401 | +} | ||||
| 2402 | +``` | ||||
| 2403 | + | ||||
| 2404 | +Returning `decision: "block"` or `continue: false` stops the agentic loop before the next model call. The blocking message comes from the JSON `reason` or `stopReason`, or from stderr on exit 2. You see it as a warning in the transcript, and it stays in the conversation, so Claude sees it when the conversation continues. | ||||
| 2405 | + | ||||
| 2406 | +### PermissionDenied | ||||
| 2407 | + | ||||
| 2408 | +Runs when [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) denies a tool call, including when it denies without a classifier verdict because [a safety check separate from auto mode refused the classifier's own request](https://code.claude.com/docs/en/errors.md#auto-mode-cannot-determine-the-safety-of-an-action) or its response didn't parse. This hook only fires in auto mode: it doesn't run when you manually deny a permission dialog, when a `PreToolUse` hook blocks a call, or when a `deny` rule matches. Use it to log denials, adjust configuration, or tell the model it may retry the tool call. | ||||
| 2409 | + | ||||
| 2410 | +Matches on tool name, same values as PreToolUse. | ||||
| 2411 | + | ||||
| 2412 | +#### PermissionDenied input | ||||
| 2413 | + | ||||
| 2414 | +In addition to the [common input fields](#common-input-fields), PermissionDenied hooks receive `tool_name`, `tool_input`, `tool_use_id`, and `reason`. For an MCP tool, they also receive the [`mcp_server`](#pretooluse-input) object. | ||||
| 2415 | + | ||||
| 2416 | +```json theme={null} | ||||
| 2417 | +{ | ||||
| 2418 | + "session_id": "abc123", | ||||
| 2419 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2420 | + "cwd": "/Users/...", | ||||
| 2421 | + "permission_mode": "auto", | ||||
| 2422 | + "hook_event_name": "PermissionDenied", | ||||
| 2423 | + "tool_name": "Bash", | ||||
| 2424 | + "tool_input": { | ||||
| 2425 | + "command": "rm -rf /tmp/build", | ||||
| 2426 | + "description": "Clean build directory" | ||||
| 2427 | + }, | ||||
| 2428 | + "tool_use_id": "toolu_01ABC123...", | ||||
| 2429 | + "reason": "[Irreversible Local Destruction]" | ||||
| 2430 | +} | ||||
| 2431 | +``` | ||||
| 2432 | + | ||||
| 2433 | +| Field | Description | | ||||
| 2434 | +| :- | :- | | ||||
| 2435 | +| `reason` | The denial reason. For a classifier verdict, in most sessions it names the matched rule in square brackets, such as `[Data Exfiltration]`; see [Review denials](https://code.claude.com/docs/en/auto-mode-config.md#review-denials) for the other forms. For a [no-verdict denial](#permissiondenied-decision-control), it starts with `Auto mode could not evaluate this action and is blocking it for safety`. For a denial because the classifier model was unavailable, it is the fixed text `Classifier unavailable` | | ||||
| 2436 | + | ||||
| 2437 | +#### PermissionDenied decision control | ||||
| 2438 | + | ||||
| 2439 | +PermissionDenied hooks can tell the model it may retry the denied tool call. Return a JSON object with `hookSpecificOutput.retry` set to `true`: | ||||
| 2440 | + | ||||
| 2441 | +```json theme={null} | ||||
| 2442 | +{ | ||||
| 2443 | + "hookSpecificOutput": { | ||||
| 2444 | + "hookEventName": "PermissionDenied", | ||||
| 2445 | + "retry": true | ||||
| 2446 | + } | ||||
| 2447 | +} | ||||
| 2448 | +``` | ||||
| 2449 | + | ||||
| 2450 | +When `retry` is `true`, Claude Code adds a message to the conversation telling the model it may retry the tool call. Claude Code doesn't reverse the denial itself. If your hook doesn't return JSON, or returns `retry: false`, the denial stands and the model receives the original rejection message. | ||||
| 2451 | + | ||||
| 2452 | +Claude Code ignores `retry: true` when the classifier produced [no verdict on the action](https://code.claude.com/docs/en/errors.md#auto-mode-cannot-determine-the-safety-of-an-action): its response didn't parse, or a safety check separate from auto mode refused the classifier's own request. For those denials, Claude Code already tells the model in the rejection message whether to retry later or move on. | ||||
| 2453 | + | ||||
| 2454 | +### Notification | ||||
| 2455 | + | ||||
| 2456 | +Runs when Claude Code sends notifications. Matches on notification type. Omit the matcher to run hooks for all notification types. | ||||
| 2457 | + | ||||
| 2458 | +You receive these hook events even with desktop notifications turned off: the `preferredNotifChannel` setting, including `notifications_disabled`, changes only how you're alerted, not whether your hook runs. | ||||
| 2459 | + | ||||
| 2460 | +| Matcher | When it fires | | ||||
| 2461 | +| :- | :- | | ||||
| 2462 | +| `permission_prompt` | Claude needs you to approve a tool use or a sandboxed command's [network request](https://code.claude.com/docs/en/sandboxing.md#network-isolation), and the prompt has waited about six seconds | | ||||
| 2463 | +| `idle_prompt` | Claude finished responding about 60 seconds ago and you haven't typed since | | ||||
| 2464 | +| `auth_success` | Authentication completes | | ||||
| 2465 | +| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about six seconds | | ||||
| 2466 | +| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about six seconds | | ||||
| 2467 | +| `elicitation_complete` | An MCP server reports that a [URL-mode elicitation](#elicitation-input) is complete | | ||||
| 2468 | +| `elicitation_response` | An MCP elicitation response is sent back to the server | | ||||
| 2469 | +| `agent_needs_input` | A background session starts waiting on your input while [agent view](https://code.claude.com/docs/en/agent-view.md) is open in a terminal. Also fires when a terminal session shows you an [agent team teammate's terminal setup question](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) or auto mode's notice about [classifier request charges](https://code.claude.com/docs/en/auto-mode-classifier-billing.md) and you haven't typed for about six seconds | | ||||
| 2470 | +| `agent_completed` | A background session finishes or fails. Fires only while [agent view](https://code.claude.com/docs/en/agent-view.md) is open in a terminal | | ||||
| 2471 | +| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset) | | ||||
| 2472 | +| `quota_auto_resume_stale` | A claude.ai usage limit reset while your computer slept for more than about 30 minutes. Claude Code waits for you to press `Enter` instead of continuing. After a shorter sleep it continues and fires `quota_auto_resume_fired` instead | | ||||
| 2473 | +| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](https://code.claude.com/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** | | ||||
| 2474 | +| `plugin_notification` | A [mod](https://code.claude.com/docs/en/plugins/mods/api.md#show-something-without-starting-a-turn) raises a notification with `$.ui.notify`. The hook's `title` is the mod's name unless the mod set one | | ||||
| 2475 | + | ||||
| 2476 | +The `quota_auto_resume_fired`, `quota_auto_resume_stale`, and `quota_auto_resume_disabled` types require Claude Code v2.1.234 or later. | ||||
| 2477 | + | ||||
| 2478 | +In terminal sessions, `permission_prompt` for a sandboxed command's network request requires Claude Code v2.1.246 or later. | ||||
| 2479 | + | ||||
| 2480 | +`agent_needs_input` for a teammate's terminal setup question requires Claude Code v2.1.248 or later. | ||||
| 2481 | + | ||||
| 2482 | +> [!NOTE] | ||||
| 2483 | +> | ||||
| 2484 | +> The `permission_prompt`, `idle_prompt`, `elicitation_dialog`, and `elicitation_url_dialog` types share their timing with desktop notifications, so in terminal sessions you only see them when you appear to be away from the terminal: | ||||
| 2485 | +> | ||||
| 2486 | +> * Expect `permission_prompt` once you haven't typed for about six seconds. The timer starts when the permission prompt appears, and each keystroke defers it. To run a hook immediately when Claude asks for permission to use a tool, use [PermissionRequest](#permissionrequest) instead. | ||||
| 2487 | +> * Expect `idle_prompt` about 60 seconds after Claude finishes responding, and only if you haven't typed since and no background agent, such as a background [subagent](https://code.claude.com/docs/en/sub-agents.md), is still running. Claude Code doesn't send `idle_prompt` while it waits for a claude.ai usage limit to reset. When the wait ends on its own, one of the `quota_auto_resume_*` types fires instead. | ||||
| 2488 | +> * Expect `elicitation_dialog` for an elicitation form, or `elicitation_url_dialog` for a browser URL request, once you haven't typed for about six seconds. Both share the same six-second gate as `permission_prompt`: the timer starts when the dialog appears, and each keystroke defers it. | ||||
| 2489 | +> | ||||
| 2490 | +> A permission request or elicitation that arrives while another dialog is on screen keeps the same six-second gate, timed from when the request arrives. Its notification can reach you while the request still waits behind the open dialog. | ||||
| 2491 | + | ||||
| 2492 | +Claude Code times `permission_prompt` differently in sessions where it sends permission requests to the Agent SDK's [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/user-input), which is how Claude Desktop and the VS Code extension host Claude Code: | ||||
| 2493 | + | ||||
| 2494 | +* Expect `permission_prompt` about six seconds after Claude asks for permission. Claude Code doesn't defer it while you type. | ||||
| 2495 | +* If you or a [PermissionRequest](#permissionrequest) hook answer sooner, Claude Code doesn't run `permission_prompt`. | ||||
| 2496 | +* Set [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](https://code.claude.com/docs/en/env-vars) to `1` to turn `permission_prompt` off in these sessions. | ||||
| 2497 | + | ||||
| 2498 | +Before v2.1.233, `permission_prompt` didn't fire in these sessions. | ||||
| 2499 | + | ||||
| 2500 | +Use separate matchers to run different handlers depending on the notification type. This configuration triggers a permission-specific alert script when Claude needs permission approval and a different notification when Claude has been idle: | ||||
| 2501 | + | ||||
| 2502 | +```json theme={null} | ||||
| 2503 | +{ | ||||
| 2504 | + "hooks": { | ||||
| 2505 | + "Notification": [ | ||||
| 2506 | + { | ||||
| 2507 | + "matcher": "permission_prompt", | ||||
| 2508 | + "hooks": [ | ||||
| 2509 | + { | ||||
| 2510 | + "type": "command", | ||||
| 2511 | + "command": "/path/to/permission-alert.sh" | ||||
| 2512 | + } | ||||
| 2513 | + ] | ||||
| 2514 | + }, | ||||
| 2515 | + { | ||||
| 2516 | + "matcher": "idle_prompt", | ||||
| 2517 | + "hooks": [ | ||||
| 2518 | + { | ||||
| 2519 | + "type": "command", | ||||
| 2520 | + "command": "/path/to/idle-notification.sh" | ||||
| 2521 | + } | ||||
| 2522 | + ] | ||||
| 2523 | + } | ||||
| 2524 | + ] | ||||
| 2525 | + } | ||||
| 2526 | +} | ||||
| 2527 | +``` | ||||
| 2528 | + | ||||
| 2529 | +#### Notification input | ||||
| 2530 | + | ||||
| 2531 | +In addition to the [common input fields](#common-input-fields), Notification hooks receive `message` with the notification text, an optional `title`, and `notification_type` indicating which type fired. | ||||
| 2532 | + | ||||
| 2533 | +```json theme={null} | ||||
| 2534 | +{ | ||||
| 2535 | + "session_id": "abc123", | ||||
| 2536 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2537 | + "cwd": "/Users/...", | ||||
| 2538 | + "hook_event_name": "Notification", | ||||
| 2539 | + "message": "Claude needs your permission", | ||||
| 2540 | + "title": "Permission needed", | ||||
| 2541 | + "notification_type": "permission_prompt" | ||||
| 2542 | +} | ||||
| 2543 | +``` | ||||
| 2544 | + | ||||
| 2545 | +Notification hooks can't block or modify notifications. Claude Code discards their `systemMessage` and `continue` fields but still emits [`terminalSequence`](#emit-terminal-notifications), which is what the desktop notification example relies on. Notification hooks are intended for side effects such as forwarding the notification to an external service. | ||||
| 2546 | + | ||||
| 2547 | +### SubagentStart | ||||
| 2548 | + | ||||
| 2549 | +Runs when Claude spawns a subagent with the Agent tool, when Claude [resumes a subagent](https://code.claude.com/docs/en/sub-agents.md#resume-subagents), and each time an in-process [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate handles a new message. Supports matchers to filter by agent type name. For built-in agents, this is the agent name like `general-purpose`, `Explore`, or `Plan`. For [custom subagents](https://code.claude.com/docs/en/sub-agents.md), this is the `name` field from the agent's frontmatter, not the filename. | ||||
| 2550 | + | ||||
| 2551 | +For subagents shipped by a [plugin](https://code.claude.com/docs/en/plugins/overview.md), the agent type is the plugin-scoped identifier such as `my-plugin:reviewer`, not the bare frontmatter name. The colon places a plugin-scoped name on the regular-expression path, so anchor the matcher with `^` and `$` for an exact match: `^my-plugin:reviewer$`. | ||||
| 2552 | + | ||||
| 2553 | +#### SubagentStart input | ||||
| 2554 | + | ||||
| 2555 | +In addition to the [common input fields](#common-input-fields), SubagentStart hooks receive `agent_id` with the unique identifier for the subagent and `agent_type` with the agent name that the matcher filters on. | ||||
| 2556 | + | ||||
| 2557 | +```json theme={null} | ||||
| 2558 | +{ | ||||
| 2559 | + "session_id": "abc123", | ||||
| 2560 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2561 | + "cwd": "/Users/...", | ||||
| 2562 | + "hook_event_name": "SubagentStart", | ||||
| 2563 | + "agent_id": "agent-abc123", | ||||
| 2564 | + "agent_type": "Explore" | ||||
| 2565 | +} | ||||
| 2566 | +``` | ||||
| 2567 | + | ||||
| 2568 | +SubagentStart hooks can't block subagent creation, but they can inject context into the subagent. In addition to the [JSON output fields](#json-output) available to all hooks, you can return: | ||||
| 2569 | + | ||||
| 2570 | +| Field | Description | | ||||
| 2571 | +| :- | :- | | ||||
| 2572 | +| `additionalContext` | String added to the subagent's context at the start of its conversation, before its first prompt. See [Add context for Claude](#add-context-for-claude) | | ||||
| 2573 | + | ||||
| 2574 | +```json theme={null} | ||||
| 2575 | +{ | ||||
| 2576 | + "hookSpecificOutput": { | ||||
| 2577 | + "hookEventName": "SubagentStart", | ||||
| 2578 | + "additionalContext": "Follow security guidelines for this task" | ||||
| 2579 | + } | ||||
| 2580 | +} | ||||
| 2581 | +``` | ||||
| 2582 | + | ||||
| 2583 | +When the hook runs again for the same subagent, Claude Code injects the returned context only when the subagent's context doesn't already hold the copy from an earlier run. The copy injected at launch stays in place, leaving the subagent's [prompt cache](https://code.claude.com/docs/en/prompt-caching.md#subagents-and-the-cache) intact. After [auto-compaction](https://code.claude.com/docs/en/sub-agents.md#auto-compaction) discards that copy, Claude Code injects the next run's context again. | ||||
| 2584 | + | ||||
| 2585 | +### SubagentStop | ||||
| 2586 | + | ||||
| 2587 | +Runs when a Claude Code subagent has finished responding. Matches on agent type, same values as SubagentStart. | ||||
| 2588 | + | ||||
| 2589 | +#### SubagentStop input | ||||
| 2590 | + | ||||
| 2591 | +In addition to the [common input fields](#common-input-fields), SubagentStop hooks receive `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, and `last_assistant_message`. The `agent_type` field is the value used for matcher filtering. The `transcript_path` is the main session's transcript, while `agent_transcript_path` is the subagent's own transcript stored in a nested `subagents/` folder. The `last_assistant_message` field contains the text content of the subagent's final response, so hooks can access it without parsing the transcript file. | ||||
| 2592 | + | ||||
| 2593 | +Not every SubagentStop event comes from a subagent Claude spawned. Claude Code also runs internal agents for some of its own features, such as [prompt suggestions](https://code.claude.com/docs/en/interactive-mode.md#prompt-suggestions) and [`/btw` side questions](https://code.claude.com/docs/en/interactive-mode#side-questions-with-%2Fbtw), and SubagentStop fires when one of those finishes too. For those events, `agent_type` is the agent name the session itself runs as, such as one set with [`--agent`](https://code.claude.com/docs/en/cli-reference#cli-flags) or the [`agent` setting](https://code.claude.com/docs/en/settings-reference#agent), and an empty string when the session runs without one. | ||||
| 2594 | + | ||||
| 2595 | +A `matcher` that names agent types doesn't match an empty `agent_type`. A hook whose matcher is omitted, `""`, or `"*"`, or is a regular expression that matches an empty string, runs for events with an empty `agent_type` too. | ||||
| 2596 | + | ||||
| 2597 | +On Claude Code v2.1.271 or later, a subagent that runs with the [`SubagentHandback`](https://code.claude.com/docs/en/tools-reference) tool delivers its report through that tool before it stops. The `last_assistant_message` field then holds the subagent's closing text, if any, which is not the delivered report. The report is that call's `message` input, which a `PreToolUse` or `PostToolUse` hook matched on `SubagentHandback` receives as `tool_input.message`. | ||||
| 2598 | + | ||||
| 2599 | +SubagentStop hooks also receive the `background_tasks` and `session_crons` arrays described under [Stop input](#stop-input). Both arrays are scoped to the parent session, not the subagent. | ||||
| 2600 | + | ||||
| 2601 | +```json theme={null} | ||||
| 2602 | +{ | ||||
| 2603 | + "session_id": "abc123", | ||||
| 2604 | + "transcript_path": "~/.claude/projects/.../abc123.jsonl", | ||||
| 2605 | + "cwd": "/Users/...", | ||||
| 2606 | + "permission_mode": "default", | ||||
| 2607 | + "hook_event_name": "SubagentStop", | ||||
| 2608 | + "stop_hook_active": false, | ||||
| 2609 | + "agent_id": "def456", | ||||
| 2610 | + "agent_type": "Explore", | ||||
| 2611 | + "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl", | ||||
| 2612 | + "last_assistant_message": "Analysis complete. Found 3 potential issues...", | ||||
| 2613 | + "background_tasks": [], | ||||
| 2614 | + "session_crons": [] | ||||
| 2615 | +} | ||||
| 2616 | +``` | ||||
| 2617 | + | ||||
| 2618 | +SubagentStop hooks use the same decision control format as [Stop hooks](#stop-decision-control), including `hookSpecificOutput.additionalContext` with `hookEventName` set to `"SubagentStop"`, for non-error feedback that keeps the subagent running. Returning `decision: "block"` with a `reason` keeps the subagent running and delivers `reason` to the subagent as its next instruction. A hook that blocks by exiting 2 delivers its stderr message the same way. To inject context into the parent session after a subagent returns, use a [`PostToolUse`](#posttooluse) hook on the `Agent` tool instead. | ||||
| 2619 | + | ||||
| 2620 | +### TaskCreated | ||||
| 2621 | + | ||||
| 2622 | +Runs when a task is being created via the `TaskCreate` tool. Use this to enforce naming conventions, require task descriptions, or prevent certain tasks from being created. In a [session without the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability), this event doesn't fire. | ||||
| 2623 | + | ||||
| 2624 | +TaskCreated hooks don't support matchers and fire on every occurrence. | ||||
| 2625 | + | ||||
| 2626 | +#### TaskCreated input | ||||
| 2627 | + | ||||
| 2628 | +In addition to the [common input fields](#common-input-fields), TaskCreated hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`. | ||||
| 2629 | + | ||||
| 2630 | +```json theme={null} | ||||
| 2631 | +{ | ||||
| 2632 | + "session_id": "abc123", | ||||
| 2633 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2634 | + "cwd": "/Users/...", | ||||
| 2635 | + "hook_event_name": "TaskCreated", | ||||
| 2636 | + "task_id": "task-001", | ||||
| 2637 | + "task_subject": "Implement user authentication", | ||||
| 2638 | + "task_description": "Add login and signup endpoints", | ||||
| 2639 | + "teammate_name": "implementer", | ||||
| 2640 | + "team_name": "session-a1b2c3d4" | ||||
| 2641 | +} | ||||
| 2642 | +``` | ||||
| 2643 | + | ||||
| 2644 | +| Field | Description | | ||||
| 2645 | +| :- | :- | | ||||
| 2646 | +| `task_id` | Identifier of the task being created | | ||||
| 2647 | +| `task_subject` | Title of the task | | ||||
| 2648 | +| `task_description` | Detailed description of the task. May be absent | | ||||
| 2649 | +| `teammate_name` | Name of the teammate creating the task. May be absent | | ||||
| 2650 | +| `team_name` | Deprecated. Session-derived team name; will be removed in a future release | | ||||
| 2651 | +| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the subagent or [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) creating the task. May be absent. Requires Claude Code v2.1.290 or later | | ||||
| 2652 | + | ||||
| 2653 | +#### TaskCreated decision control | ||||
| 2654 | + | ||||
| 2655 | +A TaskCreated hook can block the creation with exit code 2 or with a JSON decision. Either way, Claude Code deletes the task and returns your message to Claude as the tool's error. Claude Code ignores `continue: false` from this event and Claude keeps working. | ||||
| 2656 | + | ||||
| 2657 | +* **Exit code 2**: Claude Code returns the stderr text as the message. | ||||
| 2658 | +* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code returns `reason` as the message. | ||||
| 2659 | + | ||||
| 2660 | +This example blocks tasks whose subjects don't follow the required format: | ||||
| 2661 | + | ||||
| 2662 | +```bash theme={null} | ||||
| 2663 | +#!/bin/bash | ||||
| 2664 | +INPUT=$(cat) | ||||
| 2665 | +TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject') | ||||
| 2666 | + | ||||
| 2667 | +if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then | ||||
| 2668 | + echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2 | ||||
| 2669 | + exit 2 | ||||
| 2670 | +fi | ||||
| 2671 | + | ||||
| 2672 | +exit 0 | ||||
| 2673 | +``` | ||||
| 2674 | + | ||||
| 2675 | +### TaskCompleted | ||||
| 2676 | + | ||||
| 2677 | +Runs when a task is being marked as completed. This fires in two situations: when any agent explicitly marks a task as completed through the TaskUpdate tool, or when an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate finishes its turn with in-progress tasks. Use this to enforce completion criteria like passing tests or lint checks before a task can close. | ||||
| 2678 | + | ||||
| 2679 | +TaskCompleted hooks don't support matchers and fire on every occurrence. | ||||
| 2680 | + | ||||
| 2681 | +#### TaskCompleted input | ||||
| 2682 | + | ||||
| 2683 | +In addition to the [common input fields](#common-input-fields), TaskCompleted hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`. | ||||
| 2684 | + | ||||
| 2685 | +```json theme={null} | ||||
| 2686 | +{ | ||||
| 2687 | + "session_id": "abc123", | ||||
| 2688 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2689 | + "cwd": "/Users/...", | ||||
| 2690 | + "permission_mode": "default", | ||||
| 2691 | + "hook_event_name": "TaskCompleted", | ||||
| 2692 | + "task_id": "task-001", | ||||
| 2693 | + "task_subject": "Implement user authentication", | ||||
| 2694 | + "task_description": "Add login and signup endpoints", | ||||
| 2695 | + "teammate_name": "implementer", | ||||
| 2696 | + "team_name": "session-a1b2c3d4" | ||||
| 2697 | +} | ||||
| 2698 | +``` | ||||
| 2699 | + | ||||
| 2700 | +| Field | Description | | ||||
| 2701 | +| :- | :- | | ||||
| 2702 | +| `task_id` | Identifier of the task being completed | | ||||
| 2703 | +| `task_subject` | Title of the task | | ||||
| 2704 | +| `task_description` | Detailed description of the task. May be absent | | ||||
| 2705 | +| `teammate_name` | Name of the teammate completing the task. May be absent | | ||||
| 2706 | +| `team_name` | Deprecated. Session-derived team name; will be removed in a future release | | ||||
| 2707 | +| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the subagent or [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) completing the task. May be absent. Requires Claude Code v2.1.290 or later | | ||||
| 2708 | + | ||||
| 2709 | +#### TaskCompleted decision control | ||||
| 2710 | + | ||||
| 2711 | +TaskCompleted hooks support two ways to control task completion: | ||||
| 2712 | + | ||||
| 2713 | +* **Exit code 2**: the task is not marked as completed and the stderr message is fed back to the model as feedback. | ||||
| 2714 | +* **JSON `{"continue": false, "stopReason": "..."}`**: when a teammate finishing its turn triggered the event, stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user. When the `TaskUpdate` tool triggered the event, Claude Code ignores `continue: false`; exit code 2 still blocks the completion. | ||||
| 2715 | + | ||||
| 2716 | +This example runs tests and blocks task completion if they fail: | ||||
| 2717 | + | ||||
| 2718 | +```bash theme={null} | ||||
| 2719 | +#!/bin/bash | ||||
| 2720 | +INPUT=$(cat) | ||||
| 2721 | +TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject') | ||||
| 2722 | + | ||||
| 2723 | +# Run the test suite | ||||
| 2724 | +if ! npm test 2>&1; then | ||||
| 2725 | + echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2 | ||||
| 2726 | + exit 2 | ||||
| 2727 | +fi | ||||
| 2728 | + | ||||
| 2729 | +exit 0 | ||||
| 2730 | +``` | ||||
| 2731 | + | ||||
| 2732 | +### Stop | ||||
| 2733 | + | ||||
| 2734 | +Runs when the main Claude Code agent has finished responding. Does not run if | ||||
| 2735 | +the stoppage occurred due to a user interrupt. API errors fire | ||||
| 2736 | +[StopFailure](#stopfailure) instead. | ||||
| 2737 | + | ||||
| 2738 | +> [!TIP] | ||||
| 2739 | +> | ||||
| 2740 | +> The [`/goal`](https://code.claude.com/docs/en/goal) command is a built-in shortcut for a session-scoped prompt-based Stop hook. Use it when you want Claude to keep working toward a condition without writing hook configuration. | ||||
| 2741 | + | ||||
| 2742 | +#### Stop input | ||||
| 2743 | + | ||||
| 2744 | +In addition to the [common input fields](#common-input-fields), Stop hooks receive `stop_hook_active`, `last_assistant_message`, `background_tasks`, and `session_crons`. The `stop_hook_active` field is `true` when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to avoid blocking on a condition that will never resolve. | ||||
| 2745 | + | ||||
| 2746 | +Claude Code applies an 8-consecutive-continuation cap: after stop hooks have continued the turn eight times in a row, Claude Code overrides the next block and ends the turn. The count of consecutive continuations resets each time Claude calls a tool. To raise the cap, set [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](https://code.claude.com/docs/en/env-vars). | ||||
| 2747 | + | ||||
| 2748 | +The `last_assistant_message` field contains the text content of Claude's final response, so hooks can access it without parsing the transcript file. For hooks that act on the just-completed turn, such as read-aloud or notification hooks, use this field rather than reading `transcript_path`: the transcript file isn't guaranteed to include the final message at Stop time on all versions. | ||||
| 2749 | + | ||||
| 2750 | +The `background_tasks` and `session_crons` arrays let hooks distinguish "session is done" from "session is paused waiting for background work to wake it back up". Both arrays are present when the task registry is reachable and are empty when nothing is in flight or scheduled. | ||||
| 2751 | + | ||||
| 2752 | +Each entry in `background_tasks` describes one in-flight task and uses these fields: | ||||
| 2753 | + | ||||
| 2754 | +| Field | Description | | ||||
| 2755 | +| :- | :- | | ||||
| 2756 | +| `id` | Task identifier | | ||||
| 2757 | +| `type` | Friendly task-type label such as `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, or `MCP task`. Each label identifies which Claude Code feature created the task. Falls back to the raw discriminant for unrecognized types | | ||||
| 2758 | +| `status` | Current task status | | ||||
| 2759 | +| `description` | Free-text description, capped at 1000 characters with an in-string `… [+N chars]` marker when clipped | | ||||
| 2760 | +| `command` | Shell command line, capped at 1000 characters. Present only for `shell` tasks | | ||||
| 2761 | +| `agent_type` | Subagent type name. Present only for `subagent` tasks | | ||||
| 2762 | +| `server` | MCP server name. Present only for `monitor` and `MCP task` tasks | | ||||
| 2763 | +| `tool` | MCP tool name. Present only for `monitor` and `MCP task` tasks | | ||||
| 2764 | +| `name` | Workflow name. Present only for `workflow` tasks | | ||||
| 2765 | + | ||||
| 2766 | +Each entry in `session_crons` describes one session-scoped scheduled wakeup, sourced from `CronCreate`, `ScheduleWakeup`, and `/loop`: | ||||
| 2767 | + | ||||
| 2768 | +| Field | Description | | ||||
| 2769 | +| :- | :- | | ||||
| 2770 | +| `id` | Cron task identifier | | ||||
| 2771 | +| `schedule` | Cron expression, for example `0 9 * * 1-5` | | ||||
| 2772 | +| `recurring` | `false` for one-shot wakeups whose schedule encodes a single fire time, `true` for tasks that re-fire on every match | | ||||
| 2773 | +| `prompt` | Prompt submitted when the cron fires, capped at 1000 characters with the same `… [+N chars]` marker | | ||||
| 2774 | + | ||||
| 2775 | +This example shows a Stop input with one in-flight shell task and one recurring cron: | ||||
| 2776 | + | ||||
| 2777 | +```json theme={null} | ||||
| 2778 | +{ | ||||
| 2779 | + "session_id": "abc123", | ||||
| 2780 | + "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2781 | + "cwd": "/Users/...", | ||||
| 2782 | + "permission_mode": "default", | ||||
| 2783 | + "hook_event_name": "Stop", | ||||
| 2784 | + "stop_hook_active": true, | ||||
| 2785 | + "last_assistant_message": "I've completed the refactoring. Here's a summary...", | ||||
| 2786 | + "background_tasks": [ | ||||
| 2787 | + { | ||||
| 2788 | + "id": "task-001", | ||||
| 2789 | + "type": "shell", | ||||
| 2790 | + "status": "running", | ||||
| 2791 | + "description": "tail logs", | ||||
| 2792 | + "command": "tail -f /var/log/syslog" | ||||
| 2793 | + } | ||||
| 2794 | + ], | ||||
| 2795 | + "session_crons": [ | ||||
| 2796 | + { | ||||
| 2797 | + "id": "cron-001", | ||||
| 2798 | + "schedule": "0 9 * * 1-5", | ||||
| 2799 | + "recurring": true, | ||||
| 2800 | + "prompt": "check the build" | ||||
| 2801 | + } | ||||
| 2802 | + ] | ||||
| 2803 | +} | ||||
| 2804 | +``` | ||||
| 2805 | + | ||||
| 2806 | +#### Stop decision control | ||||
| 2807 | + | ||||
| 2808 | +`Stop` and `SubagentStop` hooks can control whether Claude continues. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return these event-specific fields: | ||||
| 2809 | + | ||||
| 2810 | +| Field | Description | | ||||
| 2811 | +| :- | :- | | ||||
| 2812 | +| `decision` | `"block"` prevents Claude from stopping. Omit to allow Claude to stop | | ||||
| 2813 | +| `reason` | Required when `decision` is `"block"`. Tells Claude why it should continue | | ||||
| 2814 | +| `hookSpecificOutput.additionalContext` | Non-error feedback for Claude. The conversation continues so Claude can act on it, but unlike `decision: "block"` it is shown in the transcript as hook feedback rather than a hook error | | ||||
| 2815 | + | ||||
| 2816 | +A hook that blocks by exiting 2 routes the same way as `reason`: Claude receives the stderr message as the explanation for why it should continue. | ||||
| 2817 | + | ||||
| 2818 | +```json theme={null} | ||||
| 2819 | +{ | ||||
| 2820 | + "decision": "block", | ||||
| 2821 | + "reason": "Must be provided when Claude is blocked from stopping" | ||||
| 2822 | +} | ||||
| 2823 | +``` | ||||
| 2824 | + | ||||
| 2825 | +Use `additionalContext` when the hook is working as designed and giving Claude guidance, such as "run the test suite before finishing". It keeps the conversation going through the same loop protections as `decision: "block"`, namely the `stop_hook_active` input and the 8-consecutive-continuation cap, but the transcript labels it `Stop hook feedback` and no hook error notification is shown: | ||||
| 2826 | + | ||||
| 2827 | +```json theme={null} | ||||
| 2828 | +{ | ||||
| 2829 | + "hookSpecificOutput": { | ||||
| 2830 | + "hookEventName": "Stop", | ||||
| 2831 | + "additionalContext": "Please run the test suite before finishing" | ||||
| 2832 | + } | ||||
| 2833 | +} | ||||
| 2834 | +``` | ||||
| 2835 | + | ||||
| 2836 | +### StopFailure | ||||
| 2837 | + | ||||
| 2838 | +Runs instead of [Stop](#stop) when the turn ends due to an API error. Claude Code ignores the hook's output and exit code, apart from [`terminalSequence`](#emit-terminal-notifications). Use this to log failures, send alerts, or take recovery actions when Claude can't complete a response due to rate limits, authentication problems, or other API errors. | ||||
| 2839 | + | ||||
| 2840 | +#### StopFailure input | ||||
| 2841 | + | ||||
| 2842 | +In addition to the [common input fields](#common-input-fields), StopFailure hooks receive `error`, optional `error_details`, and optional `last_assistant_message`. The `error` field identifies the error type and is used for matcher filtering. | ||||
| 2843 | + | ||||
| 2844 | +| Field | Description | | ||||
| 2845 | +| :- | :- | | ||||
| 2846 | +| `error` | Error type: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, or `unknown` | | ||||
| 2847 | +| `error_details` | Additional details about the error, when available | | ||||
| 2848 | +| `last_assistant_message` | The rendered error text shown in the conversation. Unlike `Stop` and `SubagentStop`, where this field holds Claude's conversational output, for `StopFailure` it contains the API error string itself, such as `"API Error: Rate limit reached"` | | ||||
| 2849 | + | ||||
| 2850 | +```json theme={null} | ||||
| 2851 | +{ | ||||
| 2852 | + "session_id": "abc123", | ||||
| 2853 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2854 | + "cwd": "/Users/...", | ||||
| 2855 | + "hook_event_name": "StopFailure", | ||||
| 2856 | + "error": "rate_limit", | ||||
| 2857 | + "error_details": "429 Too Many Requests", | ||||
| 2858 | + "last_assistant_message": "API Error: Rate limit reached" | ||||
| 2859 | +} | ||||
| 2860 | +``` | ||||
| 2861 | + | ||||
| 2862 | +StopFailure hooks have no decision control. They run for notification and logging purposes only. | ||||
| 2863 | + | ||||
| 2864 | +### TeammateIdle | ||||
| 2865 | + | ||||
| 2866 | +Runs when an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist. | ||||
| 2867 | + | ||||
| 2868 | +TeammateIdle hooks don't support matchers and fire on every occurrence. | ||||
| 2869 | + | ||||
| 2870 | +#### TeammateIdle input | ||||
| 2871 | + | ||||
| 2872 | +In addition to the [common input fields](#common-input-fields), TeammateIdle hooks receive `teammate_name` and `team_name`. | ||||
| 2873 | + | ||||
| 2874 | +```json theme={null} | ||||
| 2875 | +{ | ||||
| 2876 | + "session_id": "abc123", | ||||
| 2877 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2878 | + "cwd": "/Users/...", | ||||
| 2879 | + "permission_mode": "default", | ||||
| 2880 | + "hook_event_name": "TeammateIdle", | ||||
| 2881 | + "teammate_name": "researcher", | ||||
| 2882 | + "team_name": "session-a1b2c3d4" | ||||
| 2883 | +} | ||||
| 2884 | +``` | ||||
| 2885 | + | ||||
| 2886 | +| Field | Description | | ||||
| 2887 | +| :- | :- | | ||||
| 2888 | +| `teammate_name` | Name of the teammate that is about to go idle | | ||||
| 2889 | +| `team_name` | Deprecated. Session-derived team name; will be removed in a future release | | ||||
| 2890 | +| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) that is about to go idle. May be absent. Requires Claude Code v2.1.290 or later | | ||||
| 2891 | + | ||||
| 2892 | +#### TeammateIdle decision control | ||||
| 2893 | + | ||||
| 2894 | +TeammateIdle hooks support two ways to control teammate behavior: | ||||
| 2895 | + | ||||
| 2896 | +* **Exit code 2**: the teammate receives the stderr message as feedback and continues working instead of going idle. | ||||
| 2897 | +* **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user. | ||||
| 2898 | + | ||||
| 2899 | +This example checks that a build artifact exists before allowing a teammate to go idle: | ||||
| 2900 | + | ||||
| 2901 | +```bash theme={null} | ||||
| 2902 | +#!/bin/bash | ||||
| 2903 | + | ||||
| 2904 | +if [ ! -f "./dist/output.js" ]; then | ||||
| 2905 | + echo "Build artifact missing. Run the build before stopping." >&2 | ||||
| 2906 | + exit 2 | ||||
| 2907 | +fi | ||||
| 2908 | + | ||||
| 2909 | +exit 0 | ||||
| 2910 | +``` | ||||
| 2911 | + | ||||
| 2912 | +### ConfigChange | ||||
| 2913 | + | ||||
| 2914 | +Runs when a configuration file changes during a session. Use this to audit settings changes, enforce security policies, or block unauthorized modifications to configuration files. | ||||
| 2915 | + | ||||
| 2916 | +Claude Code runs ConfigChange hooks when a settings file, a managed policy file, or a skill file changes. For managed policy, it runs them only when `managed-settings.json` or a file in `managed-settings.d/` changes. It applies [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) and changes to macOS managed preferences or Windows registry policy without running them. On WSL with [`wslInheritsWindowsSettings`](https://code.claude.com/docs/en/settings-reference#wslinheritswindowssettings), it also applies a changed Windows-side managed settings file on its policy poll without running them. | ||||
| 2917 | + | ||||
| 2918 | +The matcher filters on the configuration source: | ||||
| 2919 | + | ||||
| 2920 | +| Matcher | When it fires | | ||||
| 2921 | +| :- | :- | | ||||
| 2922 | +| `user_settings` | `~/.claude/settings.json` changes | | ||||
| 2923 | +| `project_settings` | `.claude/settings.json` changes | | ||||
| 2924 | +| `local_settings` | `.claude/settings.local.json` changes | | ||||
| 2925 | +| `policy_settings` | `managed-settings.json` or a file in `managed-settings.d/` changes | | ||||
| 2926 | +| `skills` | A skill file in `.claude/skills/` changes | | ||||
| 2927 | + | ||||
| 2928 | +This example logs all configuration changes for security auditing: | ||||
| 2929 | + | ||||
| 2930 | +```json theme={null} | ||||
| 2931 | +{ | ||||
| 2932 | + "hooks": { | ||||
| 2933 | + "ConfigChange": [ | ||||
| 2934 | + { | ||||
| 2935 | + "hooks": [ | ||||
| 2936 | + { | ||||
| 2937 | + "type": "command", | ||||
| 2938 | + "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh", | ||||
| 2939 | + "args": [] | ||||
| 2940 | + } | ||||
| 2941 | + ] | ||||
| 2942 | + } | ||||
| 2943 | + ] | ||||
| 2944 | + } | ||||
| 2945 | +} | ||||
| 2946 | +``` | ||||
| 2947 | + | ||||
| 2948 | +#### ConfigChange input | ||||
| 2949 | + | ||||
| 2950 | +In addition to the [common input fields](#common-input-fields), ConfigChange hooks receive `source` and optionally `file_path`. The `source` field indicates which configuration type changed, and `file_path` provides the path to the specific file that was modified. | ||||
| 2951 | + | ||||
| 2952 | +```json theme={null} | ||||
| 2953 | +{ | ||||
| 2954 | + "session_id": "abc123", | ||||
| 2955 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 2956 | + "cwd": "/Users/...", | ||||
| 2957 | + "hook_event_name": "ConfigChange", | ||||
| 2958 | + "source": "project_settings", | ||||
| 2959 | + "file_path": "/Users/.../my-project/.claude/settings.json" | ||||
| 2960 | +} | ||||
| 2961 | +``` | ||||
| 2962 | + | ||||
| 2963 | +#### ConfigChange decision control | ||||
| 2964 | + | ||||
| 2965 | +ConfigChange hooks can block configuration changes from taking effect. Use exit code 2 or a JSON `decision` to prevent the change. When blocked, the new settings are not applied to the running session. | ||||
| 2966 | + | ||||
| 2967 | +| Field | Description | | ||||
| 2968 | +| :- | :- | | ||||
| 2969 | +| `decision` | `"block"` prevents the configuration change from being applied. Omit to allow the change | | ||||
| 2970 | +| `reason` | Accepted but never shown | | ||||
| 2971 | + | ||||
| 2972 | +```json theme={null} | ||||
| 2973 | +{ | ||||
| 2974 | + "decision": "block", | ||||
| 2975 | + "reason": "Configuration changes to project settings require admin approval" | ||||
| 2976 | +} | ||||
| 2977 | +``` | ||||
| 2978 | + | ||||
| 2979 | +`policy_settings` changes can't be blocked. Hooks still fire for `policy_settings` sources when a managed settings file on the machine changes, so you can use them to log those edits, but any blocking decision is ignored. This ensures enterprise-managed settings always take effect. Claude Code doesn't run `ConfigChange` hooks when [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) arrive or refresh. | ||||
| 2980 | + | ||||
| 2981 | +Claude Code acts on the blocking decision from a ConfigChange hook's JSON output and discards `systemMessage` and `continue`. A blocked change surfaces no message to you or to Claude, whether you block with `reason` or with stderr on exit 2. Claude Code only writes a line to the debug log. | ||||
| 2982 | + | ||||
| 2983 | +### CwdChanged | ||||
| 2984 | + | ||||
| 2985 | +Runs when a shell command in the main conversation changes the working directory, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment. | ||||
| 2986 | + | ||||
| 2987 | +CwdChanged hooks have access to [`CLAUDE_ENV_FILE`](#persist-environment-variables). If your hook writes variables to that file, they persist into subsequent Bash commands until the next CwdChanged event, when Claude Code clears them. | ||||
| 2988 | + | ||||
| 2989 | +CwdChanged doesn't support matchers and fires on every occurrence. | ||||
| 2990 | + | ||||
| 2991 | +#### CwdChanged input | ||||
| 2992 | + | ||||
| 2993 | +In addition to the [common input fields](#common-input-fields), CwdChanged hooks receive `old_cwd` and `new_cwd`. | ||||
| 2994 | + | ||||
| 2995 | +```json theme={null} | ||||
| 2996 | +{ | ||||
| 2997 | + "session_id": "abc123", | ||||
| 2998 | + "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl", | ||||
| 2999 | + "cwd": "/Users/my-project/src", | ||||
| 3000 | + "hook_event_name": "CwdChanged", | ||||
| 3001 | + "old_cwd": "/Users/my-project", | ||||
| 3002 | + "new_cwd": "/Users/my-project/src" | ||||
| 3003 | +} | ||||
| 3004 | +``` | ||||
| 3005 | + | ||||
| 3006 | +#### CwdChanged output | ||||
| 3007 | + | ||||
| 3008 | +In addition to the [JSON output fields](#json-output) available to all hooks, CwdChanged hooks can return `watchPaths` to dynamically set which file paths [FileChanged](#filechanged) watches: | ||||
| 3009 | + | ||||
| 3010 | +| Field | Description | | ||||
| 3011 | +| :- | :- | | ||||
| 3012 | +| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list. Paths from your `matcher` configuration are always watched. Returning an empty array clears the dynamic list, which is typical when entering a new directory | | ||||
| 3013 | + | ||||
| 3014 | +CwdChanged hooks have no decision control. They can't block the directory change. | ||||
| 3015 | + | ||||
| 3016 | +Claude Code reads `watchPaths` and `systemMessage` from their JSON output and discards `continue`. In interactive sessions, it shows the `systemMessage` as a brief terminal notification. The message doesn't reach the SDK message stream. | ||||
| 3017 | + | ||||
| 3018 | +### DirectoryAdded | ||||
| 3019 | + | ||||
| 3020 | +Runs after you add a working directory mid-session with the `/add-dir` command, or after an SDK client adds one with the `register_repo_root` control request. Use this to prepare a newly added repository, for example by installing its dependencies. | ||||
| 3021 | + | ||||
| 3022 | +Claude Code doesn't fire this event when: | ||||
| 3023 | + | ||||
| 3024 | +* You pass a directory with the `--add-dir` startup flag; [SessionStart](#sessionstart) covers those directories | ||||
| 3025 | +* You add a directory on the `/permissions` Workspace tab | ||||
| 3026 | +* You add a directory that is already a working directory or inside one | ||||
| 3027 | + | ||||
| 3028 | +Claude Code fires DirectoryAdded after refreshing sandbox and permission state, so sandboxed tools already see the new directory when your hook runs. Hook commands themselves run unsandboxed. | ||||
| 3029 | + | ||||
| 3030 | +Claude Code doesn't wait for the hook: the add completes immediately, and the hook runs in the background with the 600-second default timeout. | ||||
| 3031 | + | ||||
| 3032 | +The matcher filters on how the directory was added: | ||||
| 3033 | + | ||||
| 3034 | +| Matcher | When it fires | | ||||
| 3035 | +| :- | :- | | ||||
| 3036 | +| `slash_command` | You add a directory with `/add-dir` | | ||||
| 3037 | +| `register_repo_root` | An SDK client adds a directory with the `register_repo_root` control request | | ||||
| 3038 | + | ||||
| 3039 | +#### DirectoryAdded input | ||||
| 3040 | + | ||||
| 3041 | +In addition to the [common input fields](#common-input-fields), DirectoryAdded hooks receive `directory` and `source`. | ||||
| 3042 | + | ||||
| 3043 | +| Field | Description | | ||||
| 3044 | +| :- | :- | | ||||
| 3045 | +| `directory` | Absolute path of the directory that was added | | ||||
| 3046 | +| `source` | How the directory was added, `"slash_command"` for `/add-dir` or `"register_repo_root"` for the SDK control request | | ||||
| 3047 | + | ||||
| 3048 | +```json theme={null} | ||||
| 3049 | +{ | ||||
| 3050 | + "session_id": "abc123", | ||||
| 3051 | + "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl", | ||||
| 3052 | + "cwd": "/Users/my-project", | ||||
| 3053 | + "hook_event_name": "DirectoryAdded", | ||||
| 3054 | + "directory": "/Users/my-other-repo", | ||||
| 3055 | + "source": "slash_command" | ||||
| 3056 | +} | ||||
| 3057 | +``` | ||||
| 3058 | + | ||||
| 3059 | +DirectoryAdded hooks have no decision control. They can't block the add, which has already completed when the hook runs. Claude Code discards the `continue` field from their JSON output and surfaces the rest differently per source: | ||||
| 3060 | + | ||||
| 3061 | +* `slash_command`: Claude Code delivers the hook's `systemMessage` to Claude as context on the next conversation turn, rather than showing it to you. A count of failed hooks appears in the transcript. Full failure output goes to the debug log | ||||
| 3062 | +* `register_repo_root`: Claude Code writes `systemMessage` output and failure output to the debug log only | ||||
| 3063 | + | ||||
| 3064 | +### FileChanged | ||||
| 3065 | + | ||||
| 3066 | +Runs when a watched file changes on disk. Claude Code detects changes with a filesystem watcher, not by inspecting tool calls, so it runs the hook no matter what changed the file: an `Edit` or `Write` tool call, a script Claude runs with `Bash`, or a process outside Claude Code entirely. A common use is reloading environment variables when project configuration files change. | ||||
| 3067 | + | ||||
| 3068 | +The `matcher` for this event serves two roles: | ||||
| 3069 | + | ||||
| 3070 | +* **Build the watch list**: the value is split on `|` and each segment is registered as a literal filename in the working directory, so `".envrc|.env"` watches exactly those two files. Regex patterns are not useful here: a value like `^\.env` would watch a file literally named `^\.env`. | ||||
| 3071 | +* **Filter which hooks run**: when a watched file changes, the same value filters which hook groups run using the standard [matcher rules](#matcher-patterns) against the changed file's basename. | ||||
| 3072 | + | ||||
| 3073 | +This example normalizes line endings in `data.csv` after any change, including a `Bash` command or an external script rewriting the file: | ||||
| 3074 | + | ||||
| 3075 | +```json theme={null} | ||||
| 3076 | +{ | ||||
| 3077 | + "hooks": { | ||||
| 3078 | + "FileChanged": [ | ||||
| 3079 | + { | ||||
| 3080 | + "matcher": "data.csv", | ||||
| 3081 | + "hooks": [ | ||||
| 3082 | + { | ||||
| 3083 | + "type": "command", | ||||
| 3084 | + "command": "/path/to/normalize-line-endings.sh" | ||||
| 3085 | + } | ||||
| 3086 | + ] | ||||
| 3087 | + } | ||||
| 3088 | + ] | ||||
| 3089 | + } | ||||
| 3090 | +} | ||||
| 3091 | +``` | ||||
| 3092 | + | ||||
| 3093 | +The hook reads the changed file's absolute path from the `file_path` field of the [JSON input](#filechanged-input) on stdin. Its `grep` guard tests for the same thing `perl` removes, a CR at the end of a line, so the run after a normalization exits without touching the file. A looser guard loops forever, because `perl -i` rewrites the file even when it substitutes nothing and Claude Code runs the hook again after every rewrite. Save this script at `/path/to/normalize-line-endings.sh` and make it executable: | ||||
| 3094 | + | ||||
| 3095 | +```bash theme={null} | ||||
| 3096 | +#!/bin/bash | ||||
| 3097 | +FILE=$(jq -r .file_path) | ||||
| 3098 | +if grep -q $'\r$' "$FILE"; then | ||||
| 3099 | + perl -pi -e 's/\r$//' "$FILE" | ||||
| 3100 | +fi | ||||
| 3101 | +``` | ||||
| 3102 | + | ||||
| 3103 | +To confirm the hook works, ask Claude to append a CRLF line to `data.csv` with a `Bash` command. Claude Code runs the hook and the file ends up with LF endings. | ||||
| 3104 | + | ||||
| 3105 | +To watch files you can't name up front, return [`watchPaths`](#filechanged-output) from a hook to update the watch list dynamically. Claude Code starts the watcher only when something names a file to watch, so seed the list with a FileChanged group whose matcher names at least one file, or with a [SessionStart](#sessionstart-decision-control) or [CwdChanged](#cwdchanged) hook that returns `watchPaths`. The matcher still filters which hook groups run when a watched file changes, so give the group that handles dynamic paths an omitted matcher, which matches every watched file and adds nothing to the watch list. A `"*"` matcher also matches every file, but Claude Code registers it in the watch list like any other value, as a literal file named `*`. | ||||
| 3106 | + | ||||
| 3107 | +FileChanged hooks have access to [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variables written to that file persist into subsequent Bash commands until the next [CwdChanged](#cwdchanged) event, when Claude Code clears them. | ||||
| 3108 | + | ||||
| 3109 | +#### FileChanged input | ||||
| 3110 | + | ||||
| 3111 | +In addition to the [common input fields](#common-input-fields), FileChanged hooks receive `file_path` and `event`. | ||||
| 3112 | + | ||||
| 3113 | +| Field | Description | | ||||
| 3114 | +| :- | :- | | ||||
| 3115 | +| `file_path` | Absolute path to the file that changed | | ||||
| 3116 | +| `event` | What happened: `"change"` for a modified file, `"add"` for a created file, or `"unlink"` for a deleted file | | ||||
| 3117 | + | ||||
| 3118 | +```json theme={null} | ||||
| 3119 | +{ | ||||
| 3120 | + "session_id": "abc123", | ||||
| 3121 | + "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl", | ||||
| 3122 | + "cwd": "/Users/my-project", | ||||
| 3123 | + "hook_event_name": "FileChanged", | ||||
| 3124 | + "file_path": "/Users/my-project/.envrc", | ||||
| 3125 | + "event": "change" | ||||
| 3126 | +} | ||||
| 3127 | +``` | ||||
| 3128 | + | ||||
| 3129 | +#### FileChanged output | ||||
| 3130 | + | ||||
| 3131 | +In addition to the [JSON output fields](#json-output) available to all hooks, FileChanged hooks can return `watchPaths` to dynamically update which file paths are watched: | ||||
| 3132 | + | ||||
| 3133 | +| Field | Description | | ||||
| 3134 | +| :- | :- | | ||||
| 3135 | +| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list. Paths from your `matcher` configuration are always watched. Use this when your hook script discovers additional files to watch based on the changed file | | ||||
| 3136 | + | ||||
| 3137 | +FileChanged hooks have no decision control. They can't block the file change from occurring. | ||||
| 3138 | + | ||||
| 3139 | +Claude Code reads `watchPaths` and `systemMessage` from their JSON output and discards `continue`. In interactive sessions, it shows the `systemMessage` as a brief terminal notification. The message doesn't reach the SDK message stream. | ||||
| 3140 | + | ||||
| 3141 | +### WorktreeCreate | ||||
| 3142 | + | ||||
| 3143 | +Runs when Claude Code creates a worktree in cases such as these: | ||||
| 3144 | + | ||||
| 3145 | +* You start a session with `claude --worktree` | ||||
| 3146 | +* Claude creates a worktree during a session and switches into it with the [`EnterWorktree`](https://code.claude.com/docs/en/tools-reference) tool | ||||
| 3147 | +* A [subagent uses `isolation: "worktree"`](https://code.claude.com/docs/en/sub-agents#choose-the-subagent-scope) | ||||
| 3148 | +* A [workflow](https://code.claude.com/docs/en/workflows.md#migrate-many-files-in-parallel) runs an agent in its own worktree | ||||
| 3149 | +* Claude Code isolates a [background session](https://code.claude.com/docs/en/agent-view.md#how-file-edits-are-isolated) in its own worktree | ||||
| 3150 | +* [`claude remote-control`](https://code.claude.com/docs/en/remote-control#start-a-remote-control-session) in `worktree` mode starts a session in its own worktree | ||||
| 3151 | + | ||||
| 3152 | +A WorktreeCreate hook doesn't run for a worktree Claude adds through Bash, and a plugin's hook doesn't run for the one created when you launch with `--worktree` and [`--tmux`](https://code.claude.com/docs/en/cli-reference#cli-flags): | ||||
| 3153 | + | ||||
| 3154 | +* **`git worktree add` through Bash**: to inspect or block that command, add a [`PreToolUse`](#pretooluse) hook with the `Bash` matcher. | ||||
| 3155 | +* **`--worktree` with `--tmux`**: Claude Code creates the worktree before it loads plugins, so a WorktreeCreate hook from a plugin doesn't run. To have your hook run with both flags, define it in a [settings file](#configuration) instead. Before v2.1.300, a plugin's WorktreeCreate hook didn't run with `--worktree` alone either. | ||||
| 3156 | + | ||||
| 3157 | +By default Claude Code creates the isolated working copy with `git worktree`. Configuring a WorktreeCreate hook replaces that default git behavior, letting you use a different version control system like SVN, Perforce, or Mercurial. | ||||
| 3158 | + | ||||
| 3159 | +Because the hook replaces the default behavior entirely, [`.worktreeinclude`](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees) is not processed. If you need to copy local configuration files like `.env` into the new worktree, do it inside your hook script. | ||||
| 3160 | + | ||||
| 3161 | +The hook must return the path to the created worktree directory. Claude Code uses this path as the working directory for the isolated session. See [WorktreeCreate output](#worktreecreate-output) for how each hook type returns the path. | ||||
| 3162 | + | ||||
| 3163 | +Claude Code acts on the hook's success and the returned path, and discards `systemMessage` and `continue`. | ||||
| 3164 | + | ||||
| 3165 | +This example creates an SVN working copy and prints the path for Claude Code to use. Replace the repository URL with your own: | ||||
| 3166 | + | ||||
| 3167 | +```json theme={null} | ||||
| 3168 | +{ | ||||
| 3169 | + "hooks": { | ||||
| 3170 | + "WorktreeCreate": [ | ||||
| 3171 | + { | ||||
| 3172 | + "hooks": [ | ||||
| 3173 | + { | ||||
| 3174 | + "type": "command", | ||||
| 3175 | + "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'" | ||||
| 3176 | + } | ||||
| 3177 | + ] | ||||
| 3178 | + } | ||||
| 3179 | + ] | ||||
| 3180 | + } | ||||
| 3181 | +} | ||||
| 3182 | +``` | ||||
| 3183 | + | ||||
| 3184 | +The hook reads the worktree `name` from the JSON input on stdin, checks out a fresh copy into a new directory, and prints the directory path. The `echo` on the last line is what Claude Code reads as the worktree path. Redirect any other output to stderr so it doesn't interfere with the path. | ||||
| 3185 | + | ||||
| 3186 | +#### WorktreeCreate input | ||||
| 3187 | + | ||||
| 3188 | +In addition to the [common input fields](#common-input-fields), WorktreeCreate hooks receive the `name` field. This is a slug identifier for the new worktree, either specified by the user or auto-generated, for example `bold-oak-a3f2`. | ||||
| 3189 | + | ||||
| 3190 | +```json theme={null} | ||||
| 3191 | +{ | ||||
| 3192 | + "session_id": "abc123", | ||||
| 3193 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3194 | + "cwd": "/Users/...", | ||||
| 3195 | + "hook_event_name": "WorktreeCreate", | ||||
| 3196 | + "name": "feature-auth" | ||||
| 3197 | +} | ||||
| 3198 | +``` | ||||
| 3199 | + | ||||
| 3200 | +#### WorktreeCreate output | ||||
| 3201 | + | ||||
| 3202 | +WorktreeCreate hooks don't use the standard allow/block decision model. Instead, the hook's success or failure determines the outcome. The hook must return the path to the created worktree directory: | ||||
| 3203 | + | ||||
| 3204 | +* **Command hooks** (`type: "command"`): print the path as the last non-empty line of stdout. Claude Code strips ANSI escape codes before reading that line, so shell startup banners printed before your `echo` are ignored. Redirect any other hook output to stderr. | ||||
| 3205 | +* **HTTP hooks** (`type: "http"`): return `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` in the response body. | ||||
| 3206 | + | ||||
| 3207 | +If the hook fails or produces no path, worktree creation fails with an error. Claude Code resolves a relative path against the directory the hook ran in, collapsing any `.` or `..` segments in it. If the resulting path isn't a directory Claude Code can enter, the session prints an error naming the path and exits with code 1. | ||||
| 3208 | + | ||||
| 3209 | +Claude Code refuses an absolute path that contains `.` or `..` segments, and any path that passes through a symlink below the repository root. The error names the rejected component. A symlink committed to the repository could redirect the worktree outside it. Return a normalized path that doesn't pass through a symlink inside the repository. | ||||
| 3210 | + | ||||
| 3211 | +### WorktreeRemove | ||||
| 3212 | + | ||||
| 3213 | +Runs when Claude Code cleans up a worktree that your [`WorktreeCreate`](#worktreecreate) hook created. The event fires when: | ||||
| 3214 | + | ||||
| 3215 | +* You exit an interactive [worktree session](https://code.claude.com/docs/en/worktrees.md#start-claude-in-a-worktree) and choose to remove the worktree when Claude Code prompts you | ||||
| 3216 | +* You exit an interactive worktree session you haven't [named](https://code.claude.com/docs/en/sessions.md#name-your-sessions), Claude Code finds no changed or untracked files, and it removes the worktree without prompting you | ||||
| 3217 | +* You delete a [background session](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) that runs in the worktree | ||||
| 3218 | +* You ask Claude to exit and remove the worktree during a session, and Claude removes it with the [`ExitWorktree`](https://code.claude.com/docs/en/tools-reference) tool | ||||
| 3219 | +* A session that [`claude remote-control`](https://code.claude.com/docs/en/remote-control#start-a-remote-control-session) started in `worktree` mode ends without crashing, and Claude Code finds no changed or untracked files and no new commits in its worktree | ||||
| 3220 | +* You stop `claude remote-control` while sessions it started in `worktree` mode are still running, and Claude Code finds no changed or untracked files and no new commits in their worktrees | ||||
| 3221 | + | ||||
| 3222 | +When a subagent or a workflow agent finishes, Claude Code keeps the worktree your WorktreeCreate hook made for it and doesn't run your WorktreeRemove hook. Remove those worktrees yourself when the work is done. | ||||
| 3223 | + | ||||
| 3224 | +Claude Code doesn't prompt you before your hook runs for an `ExitWorktree` call or a `claude remote-control` cleanup. `ExitWorktree` refuses to remove a hook-created worktree unless the call passes [`discard_changes: true`](https://code.claude.com/docs/en/agent-sdk/typescript#exitworktree), which makes your hook the last check on that route. | ||||
| 3225 | + | ||||
| 3226 | +Claude Code uses git to look for changed or untracked files, so it finds none in a worktree that isn't a git checkout or inside one, even when the directory holds uncommitted work. Check for that work in your WorktreeRemove hook before it deletes anything. | ||||
| 3227 | + | ||||
| 3228 | +For git-based worktrees, Claude Code handles cleanup automatically with `git worktree remove`. If you configured a WorktreeCreate hook, pair it with a WorktreeRemove hook to control cleanup: | ||||
| 3229 | + | ||||
| 3230 | +* **No WorktreeRemove hook**: Claude Code falls back to git for a removal at exit or through `ExitWorktree`, and keeps the worktree when `claude remote-control` cleans up: | ||||
| 3231 | + * **You exit a worktree session, or Claude calls `ExitWorktree`**: Claude Code removes the path your WorktreeCreate hook returned as `git worktree remove --force` would, so a worktree git recognizes is removed. A worktree git doesn't recognize, for example one your hook created with a non-git version control system, stays on disk. | ||||
| 3232 | + * **`claude remote-control` cleans up a session's worktree**: the worktree stays on disk, and the terminal running `claude remote-control` shows `worktree removal failed, kept: <path>`. | ||||
| 3233 | + * **You delete a background session**: see [What deleting a session removes](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes). | ||||
| 3234 | +* **Hook exits 0**: the worktree counts as removed. Claude Code reads nothing else from the hook, so make sure your hook deleted the directory. | ||||
| 3235 | +* **Hook exits non-zero**: the removal fails if the directory at `worktree_path` still exists afterward, and the worktree stays on disk with no git fallback. A hook that deleted the directory before exiting non-zero counts as removed. For how the failure is reported, see [WorktreeRemove input](#worktreeremove-input). | ||||
| 3236 | + | ||||
| 3237 | +Claude Code never deletes a branch belonging to a hook-created worktree, because it only knows the path your WorktreeCreate hook returned. If your WorktreeCreate hook creates a branch, delete it in your WorktreeRemove hook. Claude Code discards a WorktreeRemove hook's [JSON output fields](#json-output), such as `systemMessage` and `continue`. | ||||
| 3238 | + | ||||
| 3239 | +For a background-session delete, Claude Code verifies the stored worktree path before running the hook, refusing a path that is a symlink or passes through one below the repository root. On that route, the hook runs for a worktree that still contains files only when you confirm the delete in [agent view](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes). For such a worktree, [`claude rm`](https://code.claude.com/docs/en/agent-view#manage-sessions-from-the-shell) keeps the session and worktree instead. | ||||
| 3240 | + | ||||
| 3241 | +Claude Code passes the path returned by WorktreeCreate as `worktree_path` in the hook input. This example reads that path and removes the directory: | ||||
| 3242 | + | ||||
| 3243 | +```json theme={null} | ||||
| 3244 | +{ | ||||
| 3245 | + "hooks": { | ||||
| 3246 | + "WorktreeRemove": [ | ||||
| 3247 | + { | ||||
| 3248 | + "hooks": [ | ||||
| 3249 | + { | ||||
| 3250 | + "type": "command", | ||||
| 3251 | + "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'" | ||||
| 3252 | + } | ||||
| 3253 | + ] | ||||
| 3254 | + } | ||||
| 3255 | + ] | ||||
| 3256 | + } | ||||
| 3257 | +} | ||||
| 3258 | +``` | ||||
| 3259 | + | ||||
| 3260 | +#### WorktreeRemove input | ||||
| 3261 | + | ||||
| 3262 | +In addition to the [common input fields](#common-input-fields), WorktreeRemove hooks receive the `worktree_path` field, which is the absolute path to the worktree being removed. | ||||
| 3263 | + | ||||
| 3264 | +```json theme={null} | ||||
| 3265 | +{ | ||||
| 3266 | + "session_id": "abc123", | ||||
| 3267 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3268 | + "cwd": "/Users/...", | ||||
| 3269 | + "hook_event_name": "WorktreeRemove", | ||||
| 3270 | + "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth" | ||||
| 3271 | +} | ||||
| 3272 | +``` | ||||
| 3273 | + | ||||
| 3274 | +A WorktreeRemove hook's exit code decides the outcome. When a hook exits non-zero and the directory at `worktree_path` still exists afterward, the removal fails: | ||||
| 3275 | + | ||||
| 3276 | +* The worktree stays on disk, and the hook's command and stderr go to the [debug log](#debug-hooks). | ||||
| 3277 | +* If you were deleting a background session, the session stays too. The refusal message in [agent view](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) reports how the hook ended, such as `exited 1`, quotes the start of its stderr, and says whether deleting the session again removes the directory anyway. | ||||
| 3278 | +* If `claude remote-control` was cleaning up a session's worktree, the terminal running it shows `worktree removal failed, kept: <path>`. | ||||
| 3279 | + | ||||
| 3280 | +### PreCompact | ||||
| 3281 | + | ||||
| 3282 | +Runs before Claude Code is about to run a compact operation. | ||||
| 3283 | + | ||||
| 3284 | +The matcher value indicates whether compaction was triggered manually or automatically: | ||||
| 3285 | + | ||||
| 3286 | +| Matcher | When it fires | | ||||
| 3287 | +| :- | :- | | ||||
| 3288 | +| `manual` | `/compact` | | ||||
| 3289 | +| `auto` | Auto-compact when the conversation reaches the [auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window), and [idle compaction](https://code.claude.com/docs/en/settings-reference.md#idlecompaction) | | ||||
| 3290 | + | ||||
| 3291 | +Exit with code 2 to block compaction. For a manual `/compact`, the stderr message is shown to the user. You can also block by returning JSON with `"decision": "block"`. | ||||
| 3292 | + | ||||
| 3293 | +Blocking automatic compaction has different effects depending on when it fires. If compaction was triggered proactively before the context limit, Claude Code skips it and the conversation continues uncompacted. If compaction was triggered to recover from a context-limit error already returned by the API, the underlying error surfaces and the current request fails. | ||||
| 3294 | + | ||||
| 3295 | +Claude Code discards a PreCompact hook's `systemMessage` and `continue` fields. | ||||
| 3296 | + | ||||
| 3297 | +#### PreCompact input | ||||
| 3298 | + | ||||
| 3299 | +In addition to the [common input fields](#common-input-fields), PreCompact hooks receive `trigger` and `custom_instructions`. For `manual`, `custom_instructions` contains what the user passes into `/compact` and is `null` when they pass nothing. For `auto`, `custom_instructions` is `null`. | ||||
| 3300 | + | ||||
| 3301 | +```json theme={null} | ||||
| 3302 | +{ | ||||
| 3303 | + "session_id": "abc123", | ||||
| 3304 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3305 | + "cwd": "/Users/...", | ||||
| 3306 | + "hook_event_name": "PreCompact", | ||||
| 3307 | + "trigger": "manual", | ||||
| 3308 | + "custom_instructions": null | ||||
| 3309 | +} | ||||
| 3310 | +``` | ||||
| 3311 | + | ||||
| 3312 | +### PostCompact | ||||
| 3313 | + | ||||
| 3314 | +Runs after Claude Code completes a compact operation. Use this event to react to the new compacted state, for example to log the generated summary or update external state. Claude Code discards a PostCompact hook's `systemMessage` and `continue` fields. | ||||
| 3315 | + | ||||
| 3316 | +The same matcher values apply as for `PreCompact`: | ||||
| 3317 | + | ||||
| 3318 | +| Matcher | When it fires | | ||||
| 3319 | +| :- | :- | | ||||
| 3320 | +| `manual` | After `/compact` | | ||||
| 3321 | +| `auto` | After auto-compact when the conversation reaches the [auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window), and after [idle compaction](https://code.claude.com/docs/en/settings-reference.md#idlecompaction) | | ||||
| 3322 | + | ||||
| 3323 | +#### PostCompact input | ||||
| 3324 | + | ||||
| 3325 | +In addition to the [common input fields](#common-input-fields), PostCompact hooks receive `trigger` and `compact_summary`. The `compact_summary` field contains the conversation summary generated by the compact operation. | ||||
| 3326 | + | ||||
| 3327 | +```json theme={null} | ||||
| 3328 | +{ | ||||
| 3329 | + "session_id": "abc123", | ||||
| 3330 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3331 | + "cwd": "/Users/...", | ||||
| 3332 | + "hook_event_name": "PostCompact", | ||||
| 3333 | + "trigger": "manual", | ||||
| 3334 | + "compact_summary": "Summary of the compacted conversation..." | ||||
| 3335 | +} | ||||
| 3336 | +``` | ||||
| 3337 | + | ||||
| 3338 | +PostCompact hooks have no decision control. They can't affect the compaction result but can perform follow-up tasks. | ||||
| 3339 | + | ||||
| 3340 | +### PreModelSwitch | ||||
| 3341 | + | ||||
| 3342 | +Runs before Claude Code applies a model switch that you or a client requested. Use it to block a switch, require confirmation, or show what the switch will cost before it happens. | ||||
| 3343 | + | ||||
| 3344 | +PreModelSwitch requires Claude Code v2.1.251 or later. Claude Code runs it for these requests: | ||||
| 3345 | + | ||||
| 3346 | +* `/model <name>` and the `/model` picker | ||||
| 3347 | +* The `Option+P` or `Alt+P` model picker | ||||
| 3348 | +* The Model setting in `/config` | ||||
| 3349 | +* Turning on [fast mode](https://code.claude.com/docs/en/fast-mode.md) when that changes the session's model | ||||
| 3350 | +* A `set_model` request, or a model change in an `apply_flag_settings` request, from an [Agent SDK](https://code.claude.com/docs/en/agent-sdk/typescript.md#query-object) host or [Remote Control](https://code.claude.com/docs/en/remote-control.md) | ||||
| 3351 | + | ||||
| 3352 | +Claude Code doesn't run PreModelSwitch hooks for switches it makes on its own, such as an [automatic model fallback](https://code.claude.com/docs/en/model-config.md#automatic-model-fallback) or restoring the model when you resume a session. Those changes reach [PostModelSwitch](#postmodelswitch) only. | ||||
| 3353 | + | ||||
| 3354 | +Claude Code compares the matcher against the canonical name of the model the session is switching to, ignoring any `[1m]` suffix. An alias such as `opus`, a dated model ID, and a provider-specific ID such as an Amazon Bedrock model ID all match the one canonical name they resolve to, so `claude-opus-5` covers every spelling of Opus 5. | ||||
| 3355 | + | ||||
| 3356 | +When Claude Code can't determine a canonical name for the target, for example a custom model ID that only your [LLM gateway](https://code.claude.com/docs/en/llm-gateway) knows, it runs every PreModelSwitch hook regardless of matcher. A hook that blocks should therefore check `to_model` from its input rather than rely on the matcher alone. | ||||
| 3357 | + | ||||
| 3358 | +Write the matcher as an exact name, a `|`-separated list such as `claude-opus-4-6|claude-opus-5`, or a regular expression such as `.*opus.*`. This example uses an exact-name matcher and also checks `to_model` from the hook input, so it refuses a switch to Opus 4.6 by exiting with code 2 and lets any other target through: | ||||
| 3359 | + | ||||
| 3360 | +**macOS/Linux** | ||||
| 3361 | + | ||||
| 3362 | +The command checks `to_model` with `jq`: | ||||
| 3363 | + | ||||
| 3364 | +```json theme={null} | ||||
| 3365 | +{ | ||||
| 3366 | + "hooks": { | ||||
| 3367 | + "PreModelSwitch": [ | ||||
| 3368 | + { | ||||
| 3369 | + "matcher": "claude-opus-4-6", | ||||
| 3370 | + "hooks": [ | ||||
| 3371 | + { | ||||
| 3372 | + "type": "command", | ||||
| 3373 | + "command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0" | ||||
| 3374 | + } | ||||
| 3375 | + ] | ||||
| 3376 | + } | ||||
| 3377 | + ] | ||||
| 3378 | + } | ||||
| 3379 | +} | ||||
| 3380 | +``` | ||||
| 3381 | + | ||||
| 3382 | +**Windows (PowerShell)** | ||||
| 3383 | + | ||||
| 3384 | +Register a command hook that runs a script through PowerShell: | ||||
| 3385 | + | ||||
| 3386 | +```json theme={null} | ||||
| 3387 | +{ | ||||
| 3388 | + "hooks": { | ||||
| 3389 | + "PreModelSwitch": [ | ||||
| 3390 | + { | ||||
| 3391 | + "matcher": "claude-opus-4-6", | ||||
| 3392 | + "hooks": [ | ||||
| 3393 | + { | ||||
| 3394 | + "type": "command", | ||||
| 3395 | + "command": "powershell.exe", | ||||
| 3396 | + "args": [ | ||||
| 3397 | + "-NoProfile", | ||||
| 3398 | + "-ExecutionPolicy", | ||||
| 3399 | + "Bypass", | ||||
| 3400 | + "-File", | ||||
| 3401 | + "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1" | ||||
| 3402 | + ] | ||||
| 3403 | + } | ||||
| 3404 | + ] | ||||
| 3405 | + } | ||||
| 3406 | + ] | ||||
| 3407 | + } | ||||
| 3408 | +} | ||||
| 3409 | +``` | ||||
| 3410 | + | ||||
| 3411 | +Save this script to `.claude/hooks/block-opus-46.ps1` in your project: | ||||
| 3412 | + | ||||
| 3413 | +```powershell theme={null} | ||||
| 3414 | +$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json | ||||
| 3415 | +if ($hookInput.to_model -match 'opus-4-6') { | ||||
| 3416 | + [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.') | ||||
| 3417 | + exit 2 | ||||
| 3418 | +} | ||||
| 3419 | +exit 0 | ||||
| 3420 | +``` | ||||
| 3421 | + | ||||
| 3422 | +To confirm the hook works, run `/model claude-opus-4-6` from a session running a different model. Claude Code keeps the current model and reports that a PreModelSwitch hook blocked the switch, with your message as the reason. | ||||
| 3423 | + | ||||
| 3424 | +#### PreModelSwitch input | ||||
| 3425 | + | ||||
| 3426 | +In addition to the [common input fields](#common-input-fields), PreModelSwitch hooks receive the fields in this table. The last five describe what re-sending the conversation to the new model costs, so a hook can show that figure before the switch happens. | ||||
| 3427 | + | ||||
| 3428 | +| Field | Type | Description | | ||||
| 3429 | +| :- | :- | :- | | ||||
| 3430 | +| `from_model` | string | Model ID the switch changes from | | ||||
| 3431 | +| `to_model` | string | Model ID the switch changes to. The matcher compares against this model's canonical name | | ||||
| 3432 | +| `requested_model` | string or `null` | The model the request named: an alias such as `opus`, a full model ID, or `null` when the request was for the default model | | ||||
| 3433 | +| `source` | string | Where the request came from: `"command"` for `/model <name>`, the Model setting in `/config`, or turning on fast mode; `"picker"` for a model picker; `"sdk"` for a `set_model` request, or a model change in an `apply_flag_settings` request, from an Agent SDK host or Remote Control | | ||||
| 3434 | +| `context_tokens` | number | Tokens the next request re-sends as its prompt: the input, cache read, cache creation, and output tokens of the last response in the main conversation, combined. `0` before the first response | | ||||
| 3435 | +| `prompt_cache_warm` | boolean | Whether the current model's prompt cache is likely still warm, meaning the switch forfeits it | | ||||
| 3436 | +| `cache_ttl` | string | [Prompt cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime) of the main conversation at the time of this switch: `"5m"` or `"1h"` | | ||||
| 3437 | +| `estimated_cache_write_usd` | number | Estimated cost in US dollars of writing `context_tokens` to the prompt cache on `to_model` at the `cache_ttl` rate, excluding the next response. The server may not need to re-cache the whole context, so treat it as an estimate | | ||||
| 3438 | +| `pricing` | string | How Claude Code priced `estimated_cache_write_usd`: `"configured"` at your organization's own rates when it has configured them, `"catalog"` at list price, or `"default"` when `to_model` has no known price and Claude Code assumed a default rate | | ||||
| 3439 | + | ||||
| 3440 | +This example shows the input for `/model opus` in a session running Sonnet 5: | ||||
| 3441 | + | ||||
| 3442 | +```json theme={null} | ||||
| 3443 | +{ | ||||
| 3444 | + "session_id": "abc123", | ||||
| 3445 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3446 | + "cwd": "/Users/...", | ||||
| 3447 | + "hook_event_name": "PreModelSwitch", | ||||
| 3448 | + "from_model": "claude-sonnet-5", | ||||
| 3449 | + "to_model": "claude-opus-5", | ||||
| 3450 | + "requested_model": "opus", | ||||
| 3451 | + "source": "command", | ||||
| 3452 | + "context_tokens": 182340, | ||||
| 3453 | + "prompt_cache_warm": true, | ||||
| 3454 | + "cache_ttl": "5m", | ||||
| 3455 | + "estimated_cache_write_usd": 1.1396, | ||||
| 3456 | + "pricing": "catalog" | ||||
| 3457 | +} | ||||
| 3458 | +``` | ||||
| 3459 | + | ||||
| 3460 | +#### PreModelSwitch decision control | ||||
| 3461 | + | ||||
| 3462 | +`PreModelSwitch` hooks can cancel the switch, ask the user to confirm it, or let it proceed. Exit code 2 or a top-level `decision: "block"` cancels the switch. | ||||
| 3463 | + | ||||
| 3464 | +For finer control, return `permissionDecision` and `permissionDecisionReason` in a `hookSpecificOutput` object, as on [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` accepts `"allow"`, `"deny"`, and `"ask"`. It doesn't accept `"defer"`, `updatedInput`, or `additionalContext`. The table below describes both fields: | ||||
| 3465 | + | ||||
| 3466 | +| Field | Description | | ||||
| 3467 | +| :- | :- | | ||||
| 3468 | +| `permissionDecision` | `"allow"` proceeds and skips the [confirmation Claude Code shows while the prompt cache is warm](https://code.claude.com/docs/en/prompt-caching.md#switching-models). `"deny"` cancels the switch. `"ask"` prompts the user to confirm it | | ||||
| 3469 | +| `permissionDecisionReason` | For `"deny"`, shown to the user as the reason the switch was blocked, or returned as the error for a `set_model` request. For `"ask"`, shown in the confirmation prompt. Ignored for `"allow"` | | ||||
| 3470 | + | ||||
| 3471 | +Only `/model` in an interactive session can show the `"ask"` prompt. On every other surface, including non-interactive mode with the `-p` flag, `/config`, and `set_model` requests, Claude Code treats `"ask"` as a refusal. | ||||
| 3472 | + | ||||
| 3473 | +This example asks the user to confirm and quotes the token count from `context_tokens`: | ||||
| 3474 | + | ||||
| 3475 | +```json theme={null} | ||||
| 3476 | +{ | ||||
| 3477 | + "hookSpecificOutput": { | ||||
| 3478 | + "hookEventName": "PreModelSwitch", | ||||
| 3479 | + "permissionDecision": "ask", | ||||
| 3480 | + "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?" | ||||
| 3481 | + } | ||||
| 3482 | +} | ||||
| 3483 | +``` | ||||
| 3484 | + | ||||
| 3485 | +When multiple PreModelSwitch hooks return different decisions, precedence is `deny` > `ask` > `allow`. | ||||
| 3486 | + | ||||
| 3487 | +Claude Code shows the user any `systemMessage` your hook returns regardless of the decision, so a cost-report hook can return `{"systemMessage": "..."}` and exit 0. | ||||
| 3488 | + | ||||
| 3489 | +#### PreModelSwitch timeouts and other exit codes | ||||
| 3490 | + | ||||
| 3491 | +A PreModelSwitch hook that doesn't respond before its timeout blocks the switch. The default timeout for this event is 30 seconds. | ||||
| 3492 | + | ||||
| 3493 | +An exit code other than 0 or 2 without valid JSON output is a [non-blocking error](#other-exit-codes), so the switch goes ahead, except for hooks [whose failure blocks it](#block-the-action-when-a-hook-fails). | ||||
| 3494 | + | ||||
| 3495 | +### PostModelSwitch | ||||
| 3496 | + | ||||
| 3497 | +Runs after the session's model changes. Use it to give Claude model-specific guidance without editing every CLAUDE.md, for example an organization-wide instruction that applies on certain models. | ||||
| 3498 | + | ||||
| 3499 | +PostModelSwitch requires Claude Code v2.1.251 or later. It can't block, because the model has already changed. Claude Code runs PostModelSwitch hooks after any of these changes: | ||||
| 3500 | + | ||||
| 3501 | +* A switch you or a client requested | ||||
| 3502 | +* An [automatic model fallback](https://code.claude.com/docs/en/model-config.md#automatic-model-fallback), which changes the session's model | ||||
| 3503 | +* A setting such as [`opusplan`](https://code.claude.com/docs/en/model-config#opusplan-model-setting) entering or leaving plan mode | ||||
| 3504 | +* Claude Code restoring the model when you resume a session | ||||
| 3505 | + | ||||
| 3506 | +Claude Code doesn't run PostModelSwitch hooks when a model from a [fallback model chain](https://code.claude.com/docs/en/model-config.md#fallback-model-chains) serves a turn, because that substitution lasts one turn and leaves the session's model unchanged. | ||||
| 3507 | + | ||||
| 3508 | +The matcher follows the same rules as [PreModelSwitch](#premodelswitch): Claude Code compares it against the canonical name of the model the session switched to. | ||||
| 3509 | + | ||||
| 3510 | +This example adds guidance whenever the session's model changes to any Opus model: | ||||
| 3511 | + | ||||
| 3512 | +```json theme={null} | ||||
| 3513 | +{ | ||||
| 3514 | + "hooks": { | ||||
| 3515 | + "PostModelSwitch": [ | ||||
| 3516 | + { | ||||
| 3517 | + "matcher": ".*opus.*", | ||||
| 3518 | + "hooks": [ | ||||
| 3519 | + { | ||||
| 3520 | + "type": "command", | ||||
| 3521 | + "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'" | ||||
| 3522 | + } | ||||
| 3523 | + ] | ||||
| 3524 | + } | ||||
| 3525 | + ] | ||||
| 3526 | + } | ||||
| 3527 | +} | ||||
| 3528 | +``` | ||||
| 3529 | + | ||||
| 3530 | +To confirm the hook works, switch to an Opus model from a session running a different model, for example run `/model opus` from a Sonnet session, then ask Claude what guidance it has about the current model. | ||||
| 3531 | + | ||||
| 3532 | +#### PostModelSwitch input | ||||
| 3533 | + | ||||
| 3534 | +PostModelSwitch hooks receive the same fields as [PreModelSwitch](#premodelswitch-input), with `hook_event_name` set to `"PostModelSwitch"` and two more `source` values: `"auto"` for an automatic fallback or other change Claude Code made on its own, and `"resume"` for the model restored when you resume a session. | ||||
| 3535 | + | ||||
| 3536 | +`requested_model` is `null` when `source` is `"auto"`. When `source` is `"resume"`, it is the saved model setting Claude Code restored. | ||||
| 3537 | + | ||||
| 3538 | +#### PostModelSwitch decision control | ||||
| 3539 | + | ||||
| 3540 | +Claude Code takes your hook's [plain-text stdout](#exit-code-0) on exit 0, or `additionalContext` from JSON output, and delivers it to Claude with the next request after the switch. In addition to the [JSON output fields](#json-output) available to all hooks, you can return: | ||||
| 3541 | + | ||||
| 3542 | +| Field | Description | | ||||
| 3543 | +| :- | :- | | ||||
| 3544 | +| `additionalContext` | String added to Claude's context with the next request. See [Add context for Claude](#add-context-for-claude) | | ||||
| 3545 | + | ||||
| 3546 | +If the hook hasn't finished within five seconds after you send the next prompt, Claude Code sends that request without the output and attaches it to the following request instead. If the model changes several times before the next request, Claude Code delivers only the output for the last switch's target model. | ||||
| 3547 | + | ||||
| 3548 | +### SessionEnd | ||||
| 3549 | + | ||||
| 3550 | +Runs when a Claude Code session ends. Useful for cleanup tasks, logging session | ||||
| 3551 | +statistics, or saving session state. Supports matchers to filter by exit reason. | ||||
| 3552 | + | ||||
| 3553 | +The `reason` field in the hook input indicates why the session ended: | ||||
| 3554 | + | ||||
| 3555 | +| Reason | Description | | ||||
| 3556 | +| :- | :- | | ||||
| 3557 | +| `clear` | Session cleared with `/clear` command | | ||||
| 3558 | +| `resume` | Session switched via interactive `/resume` | | ||||
| 3559 | +| `logout` | User logged out | | ||||
| 3560 | +| `prompt_input_exit` | User exited while prompt input was visible | | ||||
| 3561 | +| `other` | Other exit reasons | | ||||
| 3562 | +| `bypass_permissions_disabled` | Removed in v2.1.234; Claude Code doesn't send it. Drop it from your `SessionEnd` matchers | | ||||
| 3563 | + | ||||
| 3564 | +#### SessionEnd input | ||||
| 3565 | + | ||||
| 3566 | +In addition to the [common input fields](#common-input-fields), SessionEnd hooks receive a `reason` field indicating why the session ended. See the [reason table](#sessionend) above for all values. | ||||
| 3567 | + | ||||
| 3568 | +```json theme={null} | ||||
| 3569 | +{ | ||||
| 3570 | + "session_id": "abc123", | ||||
| 3571 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3572 | + "cwd": "/Users/...", | ||||
| 3573 | + "hook_event_name": "SessionEnd", | ||||
| 3574 | + "reason": "other" | ||||
| 3575 | +} | ||||
| 3576 | +``` | ||||
| 3577 | + | ||||
| 3578 | +SessionEnd hooks have no decision control. They can't block session termination but can perform cleanup tasks. Claude Code discards their [JSON output fields](#json-output), such as `systemMessage`. | ||||
| 3579 | + | ||||
| 3580 | +SessionEnd hooks have a default timeout of 1.5 seconds. It applies when you exit, run `/clear`, or switch sessions with interactive `/resume`. You can give a hook more time in two ways: | ||||
| 3581 | + | ||||
| 3582 | +* **Per-hook `timeout`**: set `timeout` in that hook's configuration. The overall budget rises automatically to match the highest per-hook `timeout` in your settings files, up to 60 seconds. If you raise the budget this way, a hook without its own `timeout` still keeps the default. Timeouts set on plugin-provided hooks don't raise the budget. | ||||
| 3583 | +* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: set this environment variable in milliseconds to override the budget explicitly. The value you set also becomes the timeout for each hook without its own `timeout`. | ||||
| 3584 | + | ||||
| 3585 | +This example sets the budget to 5 seconds: | ||||
| 3586 | + | ||||
| 3587 | +```bash theme={null} | ||||
| 3588 | +CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude | ||||
| 3589 | +``` | ||||
| 3590 | + | ||||
| 3591 | +Before v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` raised only the overall budget, and a hook without its own `timeout` was still canceled after 1.5 seconds. | ||||
| 3592 | + | ||||
| 3593 | +### Elicitation | ||||
| 3594 | + | ||||
| 3595 | +Runs when an MCP server requests user input mid-task. By default, Claude Code shows an interactive dialog for the user to respond. Hooks can intercept this request and respond programmatically, skipping the dialog entirely. | ||||
| 3596 | + | ||||
| 3597 | +For a complete hook with its settings entry and script, see [Answer a form request from a script](#answer-a-form-request-from-a-script). | ||||
| 3598 | + | ||||
| 3599 | +The matcher field matches against the MCP server name. | ||||
| 3600 | + | ||||
| 3601 | +#### Elicitation input | ||||
| 3602 | + | ||||
| 3603 | +In addition to the [common input fields](#common-input-fields), Elicitation hooks receive `mcp_server_name`, `message`, and optional `mode`, `url`, `elicitation_id`, and `requested_schema` fields. | ||||
| 3604 | + | ||||
| 3605 | +For form-mode elicitation, the most common case: | ||||
| 3606 | + | ||||
| 3607 | +```json theme={null} | ||||
| 3608 | +{ | ||||
| 3609 | + "session_id": "abc123", | ||||
| 3610 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3611 | + "cwd": "/Users/...", | ||||
| 3612 | + "hook_event_name": "Elicitation", | ||||
| 3613 | + "mcp_server_name": "my-mcp-server", | ||||
| 3614 | + "message": "Please provide your credentials", | ||||
| 3615 | + "mode": "form", | ||||
| 3616 | + "requested_schema": { | ||||
| 3617 | + "type": "object", | ||||
| 3618 | + "properties": { | ||||
| 3619 | + "username": { "type": "string", "title": "Username" } | ||||
| 3620 | + } | ||||
| 3621 | + } | ||||
| 3622 | +} | ||||
| 3623 | +``` | ||||
| 3624 | + | ||||
| 3625 | +For URL-mode elicitation, used for browser-based authentication: | ||||
| 3626 | + | ||||
| 3627 | +```json theme={null} | ||||
| 3628 | +{ | ||||
| 3629 | + "session_id": "abc123", | ||||
| 3630 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3631 | + "cwd": "/Users/...", | ||||
| 3632 | + "hook_event_name": "Elicitation", | ||||
| 3633 | + "mcp_server_name": "my-mcp-server", | ||||
| 3634 | + "message": "Please authenticate", | ||||
| 3635 | + "mode": "url", | ||||
| 3636 | + "url": "https://auth.example.com/login" | ||||
| 3637 | +} | ||||
| 3638 | +``` | ||||
| 3639 | + | ||||
| 3640 | +#### Elicitation output | ||||
| 3641 | + | ||||
| 3642 | +An Elicitation hook can answer the request for the user, decline or cancel it, or leave it to the dialog. To answer, decline, or cancel, exit 0 and print a `hookSpecificOutput` object with an `action`. The server gets your answer and no dialog appears. Each row of this table shows what to return for one outcome and what the MCP server receives: | ||||
| 3643 | + | ||||
| 3644 | +| To | Return | The server receives | | ||||
| 3645 | +| :- | :- | :- | | ||||
| 3646 | +| Answer for the user | `"action": "accept"`, with the form field values in `content` | `accept` with your `content` | | ||||
| 3647 | +| Decline the request | `"action": "decline"` | `decline` | | ||||
| 3648 | +| Cancel the request | `"action": "cancel"` | `cancel` | | ||||
| 3649 | +| Leave the request to the user | No output, with exit code 0 | The user's answer from the [dialog](https://code.claude.com/docs/en/mcp.md#respond-to-mcp-elicitation-requests) | | ||||
| 3650 | + | ||||
| 3651 | +This output answers the form-mode request shown under [Elicitation input](#elicitation-input). The keys in `content` are the property names from that request's `requested_schema`: | ||||
| 3652 | + | ||||
| 3653 | +```json theme={null} | ||||
| 3654 | +{ | ||||
| 3655 | + "hookSpecificOutput": { | ||||
| 3656 | + "hookEventName": "Elicitation", | ||||
| 3657 | + "action": "accept", | ||||
| 3658 | + "content": { | ||||
| 3659 | + "username": "alice" | ||||
| 3660 | + } | ||||
| 3661 | + } | ||||
| 3662 | +} | ||||
| 3663 | +``` | ||||
| 3664 | + | ||||
| 3665 | +This output declines a request: | ||||
| 3666 | + | ||||
| 3667 | +```json theme={null} | ||||
| 3668 | +{ | ||||
| 3669 | + "hookSpecificOutput": { | ||||
| 3670 | + "hookEventName": "Elicitation", | ||||
| 3671 | + "action": "decline" | ||||
| 3672 | + } | ||||
| 3673 | +} | ||||
| 3674 | +``` | ||||
| 3675 | + | ||||
| 3676 | +In the dialog, selecting **Decline** sends `decline` and pressing `Esc` sends `cancel`, so return the one you want the server to see. | ||||
| 3677 | + | ||||
| 3678 | +For a URL-mode request, a hook that returns `accept` skips the dialog, so the URL never opens. | ||||
| 3679 | + | ||||
| 3680 | +Claude Code discards `reason`, `systemMessage`, and `continue` from an Elicitation hook's JSON output, whichever `action` you return. | ||||
| 3681 | + | ||||
| 3682 | +#### Other ways to decline an elicitation | ||||
| 3683 | + | ||||
| 3684 | +Your hook can also decline in these ways. The server receives the same `decline` as for `"action": "decline"`: | ||||
| 3685 | + | ||||
| 3686 | +* **Exits with code 2**: Claude Code ignores a `hookSpecificOutput` printed by the same hook | ||||
| 3687 | +* **Prints a top-level `"decision": "block"`**: the block overrides an `action` in the same output | ||||
| 3688 | + | ||||
| 3689 | +When several hooks match the same request, a decline from one of them overrides an `accept` or `cancel` from another. | ||||
| 3690 | + | ||||
| 3691 | +This script declines URL-mode requests and leaves form requests to the dialog: | ||||
| 3692 | + | ||||
| 3693 | +```bash theme={null} | ||||
| 3694 | +#!/bin/bash | ||||
| 3695 | +if [ "$(jq -r '.mode')" = "url" ]; then | ||||
| 3696 | + exit 2 | ||||
| 3697 | +fi | ||||
| 3698 | +``` | ||||
| 3699 | + | ||||
| 3700 | +Neither the user nor the server sees why your hook declined, because Claude Code doesn't show your stderr or your `reason`. | ||||
| 3701 | + | ||||
| 3702 | +Claude Code ignored a top-level `decision` from `Elicitation` and `ElicitationResult` hooks from v2.1.105 until the fix in v2.1.284. | ||||
| 3703 | + | ||||
| 3704 | +#### Answer a form request from a script | ||||
| 3705 | + | ||||
| 3706 | +This example answers one recurring question for the user. An MCP server named `issue-tracker` asks for a project key in a form, and the hook fills in `DOCS`. The script accepts when `project_key` is the form's single field. For any other request it prints nothing, so the dialog appears. | ||||
| 3707 | + | ||||
| 3708 | +**macOS/Linux** | ||||
| 3709 | + | ||||
| 3710 | +Register a command hook for the event in your settings file, with the server name as the matcher: | ||||
| 3711 | + | ||||
| 3712 | +```json theme={null} | ||||
| 3713 | +{ | ||||
| 3714 | + "hooks": { | ||||
| 3715 | + "Elicitation": [ | ||||
| 3716 | + { | ||||
| 3717 | + "matcher": "issue-tracker", | ||||
| 3718 | + "hooks": [ | ||||
| 3719 | + { | ||||
| 3720 | + "type": "command", | ||||
| 3721 | + "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh", | ||||
| 3722 | + "args": [] | ||||
| 3723 | + } | ||||
| 3724 | + ] | ||||
| 3725 | + } | ||||
| 3726 | + ] | ||||
| 3727 | + } | ||||
| 3728 | +} | ||||
| 3729 | +``` | ||||
| 3730 | + | ||||
| 3731 | +Save this script to `.claude/hooks/answer-project-key.sh` in your project and make it executable with `chmod +x`: | ||||
| 3732 | + | ||||
| 3733 | +```bash theme={null} | ||||
| 3734 | +#!/bin/bash | ||||
| 3735 | +input=$(cat) | ||||
| 3736 | +fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input") | ||||
| 3737 | + | ||||
| 3738 | +if [ "$fields" = '["project_key"]' ]; then | ||||
| 3739 | + jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}' | ||||
| 3740 | +fi | ||||
| 3741 | +``` | ||||
| 3742 | + | ||||
| 3743 | +**Windows (PowerShell)** | ||||
| 3744 | + | ||||
| 3745 | +Register a command hook that runs the script through PowerShell, with the server name as the matcher: | ||||
| 3746 | + | ||||
| 3747 | +```json theme={null} | ||||
| 3748 | +{ | ||||
| 3749 | + "hooks": { | ||||
| 3750 | + "Elicitation": [ | ||||
| 3751 | + { | ||||
| 3752 | + "matcher": "issue-tracker", | ||||
| 3753 | + "hooks": [ | ||||
| 3754 | + { | ||||
| 3755 | + "type": "command", | ||||
| 3756 | + "command": "powershell.exe", | ||||
| 3757 | + "args": [ | ||||
| 3758 | + "-NoProfile", | ||||
| 3759 | + "-ExecutionPolicy", | ||||
| 3760 | + "Bypass", | ||||
| 3761 | + "-File", | ||||
| 3762 | + "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1" | ||||
| 3763 | + ] | ||||
| 3764 | + } | ||||
| 3765 | + ] | ||||
| 3766 | + } | ||||
| 3767 | + ] | ||||
| 3768 | + } | ||||
| 3769 | +} | ||||
| 3770 | +``` | ||||
| 3771 | + | ||||
| 3772 | +Save this script to `.claude/hooks/answer-project-key.ps1` in your project: | ||||
| 3773 | + | ||||
| 3774 | +```powershell theme={null} | ||||
| 3775 | +$request = [Console]::In.ReadToEnd() | ConvertFrom-Json | ||||
| 3776 | +$fields = @($request.requested_schema.properties.PSObject.Properties.Name) | ||||
| 3777 | + | ||||
| 3778 | +if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') { | ||||
| 3779 | + @{ | ||||
| 3780 | + hookSpecificOutput = @{ | ||||
| 3781 | + hookEventName = "Elicitation" | ||||
| 3782 | + action = "accept" | ||||
| 3783 | + content = @{ project_key = "DOCS" } | ||||
| 3784 | + } | ||||
| 3785 | + } | ConvertTo-Json -Depth 3 | ||||
| 3786 | +} | ||||
| 3787 | +``` | ||||
| 3788 | + | ||||
| 3789 | +To confirm the hook works, start Claude Code with `claude --debug` and give Claude a task that makes the server ask for the project key. No dialog appears, and the [debug log](#debug-hooks) has a line that ends with `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`. | ||||
| 3790 | + | ||||
| 3791 | +### ElicitationResult | ||||
| 3792 | + | ||||
| 3793 | +Runs after a user responds to an MCP elicitation. Hooks can observe, modify, or block the response before it is sent back to the MCP server. | ||||
| 3794 | + | ||||
| 3795 | +When an [Elicitation](#elicitation) hook answers a request, Claude Code sends that answer to the server without running ElicitationResult hooks. | ||||
| 3796 | + | ||||
| 3797 | +The matcher field matches against the MCP server name. | ||||
| 3798 | + | ||||
| 3799 | +#### ElicitationResult input | ||||
| 3800 | + | ||||
| 3801 | +In addition to the [common input fields](#common-input-fields), ElicitationResult hooks receive `mcp_server_name`, `action`, and optional `mode`, `elicitation_id`, and `content` fields. | ||||
| 3802 | + | ||||
| 3803 | +```json theme={null} | ||||
| 3804 | +{ | ||||
| 3805 | + "session_id": "abc123", | ||||
| 3806 | + "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", | ||||
| 3807 | + "cwd": "/Users/...", | ||||
| 3808 | + "hook_event_name": "ElicitationResult", | ||||
| 3809 | + "mcp_server_name": "my-mcp-server", | ||||
| 3810 | + "action": "accept", | ||||
| 3811 | + "content": { "username": "alice" }, | ||||
| 3812 | + "mode": "form" | ||||
| 3813 | +} | ||||
| 3814 | +``` | ||||
| 3815 | + | ||||
| 3816 | +#### ElicitationResult output | ||||
| 3817 | + | ||||
| 3818 | +An ElicitationResult hook can let the user's response through, change its values, or block it. To change or block the response, exit 0 and print a `hookSpecificOutput` object with an `action`. Each row of this table shows what to return for one outcome and what the MCP server receives: | ||||
| 3819 | + | ||||
| 3820 | +| To | Return | The server receives | | ||||
| 3821 | +| :- | :- | :- | | ||||
| 3822 | +| Let the response through | No output, with exit code 0 | The user's response, unchanged | | ||||
| 3823 | +| Change the submitted values | `"action": "accept"`, with the new values in `content` | `accept` with your `content` in place of the user's values | | ||||
| 3824 | +| Block the response | `"action": "decline"` | `decline`, without the user's values | | ||||
| 3825 | +| Cancel the request | `"action": "cancel"` | `cancel`, along with the values the user submitted. To withhold them, return `"decline"` | | ||||
| 3826 | + | ||||
| 3827 | +This output changes the response shown under [ElicitationResult input](#elicitationresult-input), so the server receives `alice@example.com` where the user submitted `alice`: | ||||
| 3828 | + | ||||
| 3829 | +```json theme={null} | ||||
| 3830 | +{ | ||||
| 3831 | + "hookSpecificOutput": { | ||||
| 3832 | + "hookEventName": "ElicitationResult", | ||||
| 3833 | + "action": "accept", | ||||
| 3834 | + "content": { | ||||
| 3835 | + "username": "alice@example.com" | ||||
| 3836 | + } | ||||
| 3837 | + } | ||||
| 3838 | +} | ||||
| 3839 | +``` | ||||
| 3840 | + | ||||
| 3841 | +Your `content` replaces the user's whole `content` object, so include the fields you aren't changing. Return `action` along with it, because Claude Code ignores a `hookSpecificOutput` that has no `action`. | ||||
| 3842 | + | ||||
| 3843 | +ElicitationResult hooks also run when the user declines or cancels, and your `action` replaces theirs. Check that the input's `action` is `accept` before you return `accept`, or your hook turns a declined request into an accepted one. This script makes the same change when the user accepted, keeps the other fields, and prints nothing otherwise: | ||||
| 3844 | + | ||||
| 3845 | +```bash theme={null} | ||||
| 3846 | +#!/bin/bash | ||||
| 3847 | +input=$(cat) | ||||
| 3848 | + | ||||
| 3849 | +if [ "$(jq -r '.action' <<<"$input")" = "accept" ]; then | ||||
| 3850 | + jq '{hookSpecificOutput: {hookEventName: "ElicitationResult", action: "accept", content: (.content + {username: (.content.username + "@example.com")})}}' <<<"$input" | ||||
| 3851 | +fi | ||||
| 3852 | +``` | ||||
| 3853 | + | ||||
| 3854 | +This output blocks the response: | ||||
| 3855 | + | ||||
| 3856 | +```json theme={null} | ||||
| 3857 | +{ | ||||
| 3858 | + "hookSpecificOutput": { | ||||
| 3859 | + "hookEventName": "ElicitationResult", | ||||
| 3860 | + "action": "decline" | ||||
| 3861 | + } | ||||
| 3862 | +} | ||||
| 3863 | +``` | ||||
| 3864 | + | ||||
| 3865 | +Exit code 2 and a top-level `"decision": "block"` also block the response. [Other ways to decline an elicitation](#other-ways-to-decline-an-elicitation) covers which one takes effect when a hook combines them, what the user sees, and which versions ignored `decision`. | ||||
| 3866 | + | ||||
| 3867 | +Claude Code discards `reason`, `systemMessage`, and `continue` from an ElicitationResult hook's JSON output, whichever `action` you return. | ||||
| 3868 | + | ||||
| 3869 | +## Prompt-based hooks | ||||
| 3870 | + | ||||
| 3871 | +In addition to command, HTTP, and MCP tool hooks, Claude Code supports prompt-based hooks (`type: "prompt"`) that use an LLM to evaluate whether to allow or block an action, and agent hooks (`type: "agent"`) that spawn an agentic verifier with tool access. Not all events support every hook type. | ||||
| 3872 | + | ||||
| 3873 | +Events that support all five hook types (`command`, `http`, `mcp_tool`, `prompt`, and `agent`): | ||||
| 3874 | + | ||||
| 3875 | +* `PermissionDenied` | ||||
| 3876 | +* `PostToolBatch` | ||||
| 3877 | +* `PostToolUse` | ||||
| 3878 | +* `PostToolUseFailure` | ||||
| 3879 | +* `PreToolUse` | ||||
| 3880 | +* `Stop` | ||||
| 3881 | +* `SubagentStop` | ||||
| 3882 | +* `TaskCompleted` | ||||
| 3883 | +* `TaskCreated` | ||||
| 3884 | +* `TeammateIdle` | ||||
| 3885 | +* `UserPromptExpansion` | ||||
| 3886 | +* `UserPromptSubmit` | ||||
| 3887 | + | ||||
| 3888 | +`PermissionRequest` supports `command`, `http`, `mcp_tool`, and `prompt` hooks but not `agent` hooks. If you configure an agent hook on this event, Claude Code skips it and the permission flow proceeds unchanged. To allow or deny from a hook, return the [decision object](#permissionrequest-decision-control) from a command or HTTP hook. | ||||
| 3889 | + | ||||
| 3890 | +Events that support `command`, `http`, and `mcp_tool` hooks but not `prompt` or `agent`: | ||||
| 3891 | + | ||||
| 3892 | +* `ConfigChange` | ||||
| 3893 | +* `CwdChanged` | ||||
| 3894 | +* `DirectoryAdded` | ||||
| 3895 | +* `Elicitation` | ||||
| 3896 | +* `ElicitationResult` | ||||
| 3897 | +* `FileChanged` | ||||
| 3898 | +* `InstructionsLoaded` | ||||
| 3899 | +* `MessageDisplay` | ||||
| 3900 | +* `Notification` | ||||
| 3901 | +* `PostCompact` | ||||
| 3902 | +* `PostModelSwitch` | ||||
| 3903 | +* `PreCompact` | ||||
| 3904 | +* `PreModelSwitch` | ||||
| 3905 | +* `SessionEnd` | ||||
| 3906 | +* `StopFailure` | ||||
| 3907 | +* `SubagentStart` | ||||
| 3908 | +* `WorktreeCreate` | ||||
| 3909 | +* `WorktreeRemove` | ||||
| 3910 | + | ||||
| 3911 | +`SessionStart` and `Setup` support `command` and `mcp_tool` hooks, and [MCP tool hook fields](#mcp-tool-hook-fields) describes when their `mcp_tool` hooks run. They don't support `http`, `prompt`, or `agent` hooks. | ||||
| 3912 | + | ||||
| 3913 | +### How prompt-based hooks work | ||||
| 3914 | + | ||||
| 3915 | +Instead of executing a Bash command, prompt-based hooks: | ||||
| 3916 | + | ||||
| 3917 | +1. Send the hook input and your prompt to a Claude model, by default the one Claude Code uses for [background functionality](https://code.claude.com/docs/en/costs.md#background-token-usage) | ||||
| 3918 | +2. The LLM responds with structured JSON containing a decision | ||||
| 3919 | +3. Claude Code processes the decision automatically | ||||
| 3920 | + | ||||
| 3921 | +### Prompt hook configuration | ||||
| 3922 | + | ||||
| 3923 | +Set `type` to `"prompt"` and provide a `prompt` string instead of a `command`. Use the `$ARGUMENTS` placeholder to inject the hook's JSON input data into your prompt text. | ||||
| 3924 | + | ||||
| 3925 | +In a prompt or [agent hook](#agent-based-hooks), you can write the `prompt` as a rule about what to block or allow, such as "Block any Bash command that reads `.env` files", or as a condition that must hold, such as "All unit tests pass". | ||||
| 3926 | + | ||||
| 3927 | +This `Stop` hook asks the LLM to evaluate whether all tasks are complete before allowing Claude to finish: | ||||
| 3928 | + | ||||
| 3929 | +```json theme={null} | ||||
| 3930 | +{ | ||||
| 3931 | + "hooks": { | ||||
| 3932 | + "Stop": [ | ||||
| 3933 | + { | ||||
| 3934 | + "hooks": [ | ||||
| 3935 | + { | ||||
| 3936 | + "type": "prompt", | ||||
| 3937 | + "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete." | ||||
| 3938 | + } | ||||
| 3939 | + ] | ||||
| 3940 | + } | ||||
| 3941 | + ] | ||||
| 3942 | + } | ||||
| 3943 | +} | ||||
| 3944 | +``` | ||||
| 3945 | + | ||||
| 3946 | +| Field | Required | Description | | ||||
| 3947 | +| :- | :- | :- | | ||||
| 3948 | +| `type` | yes | Must be `"prompt"` | | ||||
| 3949 | +| `prompt` | yes | The prompt text to send to the LLM. Use `$ARGUMENTS` as a placeholder for the hook input JSON. If `$ARGUMENTS` is not present, input JSON is appended to the prompt | | ||||
| 3950 | +| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](https://code.claude.com/docs/en/costs.md#background-token-usage) | | ||||
| 3951 | +| `timeout` | no | Timeout in seconds. Default: 30 | | ||||
| 3952 | +| `continueOnBlock` | no | On the events it applies to, `true` feeds an `ok: false` reason back to Claude and continues instead of ending the turn. Default: `false`. See [Response schema](#response-schema) for per-event behavior | | ||||
| 3953 | + | ||||
| 3954 | +### Response schema | ||||
| 3955 | + | ||||
| 3956 | +The LLM must respond with JSON containing: | ||||
| 3957 | + | ||||
| 3958 | +```json theme={null} | ||||
| 3959 | +{ | ||||
| 3960 | + "ok": true | false, | ||||
| 3961 | + "reason": "Explanation for the decision", | ||||
| 3962 | + "impossible": true | false | ||||
| 3963 | +} | ||||
| 3964 | +``` | ||||
| 3965 | + | ||||
| 3966 | +| Field | Description | | ||||
| 3967 | +| :- | :- | | ||||
| 3968 | +| `ok` | `true` to allow. For `false`, see the per-event behavior below | | ||||
| 3969 | +| `reason` | Required when `ok` is `false` | | ||||
| 3970 | +| `impossible` | Optional. The model returns it with `ok: false` when it judges the condition can never be satisfied. On `Stop` and `SubagentStop`, Claude Code then lets the turn end instead of feeding the reason back. Agent hooks and other events ignore it | | ||||
| 3971 | + | ||||
| 3972 | +What happens on `ok: false` depends on the event: | ||||
| 3973 | + | ||||
| 3974 | +* `Stop` and `SubagentStop`: the reason is fed back to Claude as its next instruction and the turn continues, unless the response also sets `impossible: true`, in which case Claude Code allows the stop and the turn ends | ||||
| 3975 | +* `PreToolUse`: the tool call is denied; by default the turn ends and the deny reason appears in the chat as a warning line. Set `continueOnBlock: true` to instead return the reason to Claude as the tool error so it can adjust and continue, equivalent to a command hook's `permissionDecision: "deny"` | ||||
| 3976 | +* `PostToolUse`: by default the turn ends and the reason appears in the chat as a warning line. Set `continueOnBlock: true` to feed the reason back to Claude and continue the turn instead | ||||
| 3977 | +* `PostToolBatch`, `UserPromptSubmit`, and `UserPromptExpansion`: the turn ends and the reason appears as a warning line. These events end the turn on `decision: "block"` regardless of `continue` | ||||
| 3978 | +* `PostToolUseFailure` and `TaskCreated`: the reason is returned to Claude as a tool error and the turn continues, regardless of `continueOnBlock` | ||||
| 3979 | +* `TaskCompleted`: when it fires because a task is marked completed during a turn, the reason is returned to Claude as a tool error and the turn continues, regardless of `continueOnBlock`. When it fires because a teammate stops, it behaves like `TeammateIdle` and halts the teammate by default | ||||
| 3980 | +* `TeammateIdle`: by default the teammate stops and the reason appears as a warning line. Set `continueOnBlock: true` to feed the reason back to the teammate and keep it working instead | ||||
| 3981 | +* `PermissionRequest`: `ok: false` has no effect. To deny an approval from a hook, use a [command hook](#command-hook-fields) returning `hookSpecificOutput.decision.behavior: "deny"` | ||||
| 3982 | +* `PermissionDenied`: `ok: false` has no effect because the denial already happened. The only output this event reads is `hookSpecificOutput.retry`, which prompt and agent hooks can't set. They run on this event, but their output is discarded. Use a [command hook](#command-hook-fields) to return `retry` | ||||
| 3983 | + | ||||
| 3984 | +If you need finer control on any event, use a [command hook](#command-hook-fields) with the per-event fields described in [Decision control](#decision-control). | ||||
| 3985 | + | ||||
| 3986 | +### Check multiple conditions before stopping | ||||
| 3987 | + | ||||
| 3988 | +This `Stop` hook uses a detailed prompt to check three conditions before allowing Claude to stop. `SubagentStop` hooks use the same format to evaluate whether a [subagent](https://code.claude.com/docs/en/sub-agents.md) should stop. If the model returns `"ok": false` because the condition isn't met yet, Claude continues working with the provided reason as its next instruction: | ||||
| 3989 | + | ||||
| 3990 | +```json theme={null} | ||||
| 3991 | +{ | ||||
| 3992 | + "hooks": { | ||||
| 3993 | + "Stop": [ | ||||
| 3994 | + { | ||||
| 3995 | + "hooks": [ | ||||
| 3996 | + { | ||||
| 3997 | + "type": "prompt", | ||||
| 3998 | + "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.", | ||||
| 3999 | + "timeout": 30 | ||||
| 4000 | + } | ||||
| 4001 | + ] | ||||
| 4002 | + } | ||||
| 4003 | + ] | ||||
| 4004 | + } | ||||
| 4005 | +} | ||||
| 4006 | +``` | ||||
| 4007 | + | ||||
| 4008 | +## Agent-based hooks | ||||
| 4009 | + | ||||
| 4010 | +> [!WARNING] | ||||
| 4011 | +> | ||||
| 4012 | +> Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](#command-hook-fields). | ||||
| 4013 | + | ||||
| 4014 | +Agent-based hooks (`type: "agent"`) are like prompt-based hooks but with multi-turn tool access. Instead of a single LLM call, an agent hook spawns a subagent that can read files, search code, and inspect the codebase to verify conditions. Agent hooks support the same events as [prompt-based hooks](#prompt-based-hooks), except `PermissionRequest`. | ||||
| 4015 | + | ||||
| 4016 | +### How agent hooks work | ||||
| 4017 | + | ||||
| 4018 | +When an agent hook fires: | ||||
| 4019 | + | ||||
| 4020 | +1. Claude Code spawns a subagent with your prompt and the hook's JSON input | ||||
| 4021 | +2. The subagent can use tools like Read, Grep, and Glob to investigate | ||||
| 4022 | +3. After up to 50 turns, the subagent returns a structured `{ "ok": true/false }` decision | ||||
| 4023 | +4. Claude Code allows the action if `ok` is `true`. If `ok` is `false`, Claude Code handles the block the same way as a prompt hook with `continueOnBlock: true` on that event, as listed under [Response schema](#response-schema) | ||||
| 4024 | + | ||||
| 4025 | +Agent hooks are useful when verification requires inspecting actual files or test output, not just evaluating the hook input data alone. | ||||
| 4026 | + | ||||
| 4027 | +### Agent hook configuration | ||||
| 4028 | + | ||||
| 4029 | +Set `type` to `"agent"` and provide a `prompt` string, using `$ARGUMENTS` as a placeholder for the hook input JSON. The configuration fields are the same as [prompt hooks](#prompt-hook-configuration), except that agent hooks have a longer default timeout of 60 seconds and no `continueOnBlock` field. | ||||
| 4030 | + | ||||
| 4031 | +The response schema is `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block. On `ok: false`, Claude Code handles an agent hook the way it handles a [prompt hook with `continueOnBlock: true`](#response-schema) on the same event; agent hooks have no `continueOnBlock` field, and don't support the prompt-hook `impossible` field. | ||||
| 4032 | + | ||||
| 4033 | +This `Stop` hook verifies that all unit tests pass before allowing Claude to finish: | ||||
| 4034 | + | ||||
| 4035 | +```json theme={null} | ||||
| 4036 | +{ | ||||
| 4037 | + "hooks": { | ||||
| 4038 | + "Stop": [ | ||||
| 4039 | + { | ||||
| 4040 | + "hooks": [ | ||||
| 4041 | + { | ||||
| 4042 | + "type": "agent", | ||||
| 4043 | + "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS", | ||||
| 4044 | + "timeout": 120 | ||||
| 4045 | + } | ||||
| 4046 | + ] | ||||
| 4047 | + } | ||||
| 4048 | + ] | ||||
| 4049 | + } | ||||
| 4050 | +} | ||||
| 4051 | +``` | ||||
| 4052 | + | ||||
| 4053 | +## Run hooks in the background | ||||
| 4054 | + | ||||
| 4055 | +By default, hooks block Claude's execution until they complete. For long-running tasks like deployments, test suites, or external API calls, set `"async": true` to run the hook in the background while Claude continues working. Async hooks can't block or control Claude's behavior: response fields like `decision`, `permissionDecision`, and `continue` have no effect, because the action they would have controlled has already completed. | ||||
| 4056 | + | ||||
| 4057 | +### Configure an async hook | ||||
| 4058 | + | ||||
| 4059 | +Add `"async": true` to a command hook's configuration to run it in the background without blocking Claude. This field is only available on `type: "command"` hooks. | ||||
| 4060 | + | ||||
| 4061 | +This hook runs a test script after every `Write` tool call. Claude continues working immediately while `run-tests.sh` executes. When the script finishes, its output is delivered on the next conversation turn: | ||||
| 4062 | + | ||||
| 4063 | +```json theme={null} | ||||
| 4064 | +{ | ||||
| 4065 | + "hooks": { | ||||
| 4066 | + "PostToolUse": [ | ||||
| 4067 | + { | ||||
| 4068 | + "matcher": "Write", | ||||
| 4069 | + "hooks": [ | ||||
| 4070 | + { | ||||
| 4071 | + "type": "command", | ||||
| 4072 | + "command": "/path/to/run-tests.sh", | ||||
| 4073 | + "async": true | ||||
| 4074 | + } | ||||
| 4075 | + ] | ||||
| 4076 | + } | ||||
| 4077 | + ] | ||||
| 4078 | + } | ||||
| 4079 | +} | ||||
| 4080 | +``` | ||||
| 4081 | + | ||||
| 4082 | +Once an async hook is running in the background, Claude Code doesn't enforce `timeout` on it. Claude Code still enforces `timeout` on a hook you run with `asyncRewake`. | ||||
| 4083 | + | ||||
| 4084 | +Claude Code delivers an async hook's results only while the session runs: | ||||
| 4085 | + | ||||
| 4086 | +* In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, Claude Code kills any async hook still running at teardown and finalizes it with outcome `cancelled` | ||||
| 4087 | +* If your hook's work must outlive a `claude -p` session, start a fully detached process from it | ||||
| 4088 | + | ||||
| 4089 | +### How async hooks execute | ||||
| 4090 | + | ||||
| 4091 | +When an async hook fires, Claude Code starts the hook process and immediately continues without waiting for it to finish. The hook receives the same JSON input via stdin as a synchronous hook. | ||||
| 4092 | + | ||||
| 4093 | +After the background process exits, Claude Code delivers the `additionalContext` and `systemMessage` fields from the hook's JSON response to Claude on the next conversation turn, except for [repeated `SessionStart` output](#limitations). Unlike a synchronous hook's `systemMessage`, neither field is shown to you. | ||||
| 4094 | + | ||||
| 4095 | +Print the JSON response alone on stdout or on one line of its own: | ||||
| 4096 | + | ||||
| 4097 | +* **Alone on stdout**: when the response is the only text on stdout, it can span several lines, such as pretty-printed `jq` output. Spanning several lines requires Claude Code v2.1.295 or later. | ||||
| 4098 | +* **On one line of its own**: an async hook can print other text to stdout when the response fits on one line by itself, for example with `jq -c`. | ||||
| 4099 | + | ||||
| 4100 | +Claude Code validates that JSON response against the same [output schema](#json-output) as synchronous hooks, and drops any field whose value has the wrong type, such as a `systemMessage` that isn't a string, instead of delivering it. Run with `--debug` to see a warning naming each dropped field. | ||||
| 4101 | + | ||||
| 4102 | +Async hook completion notifications are suppressed by default. To see them, enable verbose mode with `Ctrl+O` or start Claude Code with `--verbose`. | ||||
| 4103 | + | ||||
| 4104 | +### Run tests after file changes | ||||
| 4105 | + | ||||
| 4106 | +This hook starts a test suite in the background whenever Claude writes a file, then reports the results back to Claude when the tests finish. Save this script to `.claude/hooks/run-tests-async.sh` in your project and make it executable with `chmod +x`: | ||||
| 4107 | + | ||||
| 4108 | +```bash theme={null} | ||||
| 4109 | +#!/bin/bash | ||||
| 4110 | +# run-tests-async.sh | ||||
| 4111 | + | ||||
| 4112 | +# Read hook input from stdin | ||||
| 4113 | +INPUT=$(cat) | ||||
| 4114 | +FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') | ||||
| 4115 | + | ||||
| 4116 | +# Only run tests for source files | ||||
| 4117 | +if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then | ||||
| 4118 | + exit 0 | ||||
| 4119 | +fi | ||||
| 4120 | + | ||||
| 4121 | +# Run tests and report results to Claude via additionalContext | ||||
| 4122 | +RESULT=$(npm test 2>&1) | ||||
| 4123 | +EXIT_CODE=$? | ||||
| 4124 | + | ||||
| 4125 | +if [ $EXIT_CODE -eq 0 ]; then | ||||
| 4126 | + MSG="Tests passed after editing $FILE_PATH" | ||||
| 4127 | +else | ||||
| 4128 | + MSG="Tests failed after editing $FILE_PATH: $RESULT" | ||||
| 4129 | +fi | ||||
| 4130 | +jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}' | ||||
| 4131 | +``` | ||||
| 4132 | + | ||||
| 4133 | +Then add this configuration to `.claude/settings.json` in your project root. The `async: true` flag lets Claude keep working while tests run: | ||||
| 4134 | + | ||||
| 4135 | +```json theme={null} | ||||
| 4136 | +{ | ||||
| 4137 | + "hooks": { | ||||
| 4138 | + "PostToolUse": [ | ||||
| 4139 | + { | ||||
| 4140 | + "matcher": "Write|Edit", | ||||
| 4141 | + "hooks": [ | ||||
| 4142 | + { | ||||
| 4143 | + "type": "command", | ||||
| 4144 | + "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh", | ||||
| 4145 | + "args": [], | ||||
| 4146 | + "async": true | ||||
| 4147 | + } | ||||
| 4148 | + ] | ||||
| 4149 | + } | ||||
| 4150 | + ] | ||||
| 4151 | + } | ||||
| 4152 | +} | ||||
| 4153 | +``` | ||||
| 4154 | + | ||||
| 4155 | +### Limitations | ||||
| 4156 | + | ||||
| 4157 | +Async hooks have additional constraints compared to synchronous hooks: | ||||
| 4158 | + | ||||
| 4159 | +* Hook output is delivered on the next conversation turn. If the session is idle, the response waits until the next user interaction. Exception: an `asyncRewake` hook that exits with code 2 wakes Claude immediately even when the session is idle. | ||||
| 4160 | +* Each execution creates a separate background process. | ||||
| 4161 | +* An async `SessionStart` hook runs every time the event fires. Claude Code skips the hook's output when the `additionalContext` and `systemMessage` text matches what Claude last received from that hook, unless a synchronous `SessionStart` hook has added other text since. Claude Code delivers the text when it changes, and again the next time the hook runs after a compaction or `/clear`. Before v2.1.295, Claude Code added the same text to the conversation again on every resume. | ||||
| 4162 | + | ||||
| 4163 | +## Security considerations | ||||
| 4164 | + | ||||
| 4165 | +### Disclaimer | ||||
| 4166 | + | ||||
| 4167 | +> [!WARNING] | ||||
| 4168 | +> | ||||
| 4169 | +> Command hooks execute shell commands with your full user permissions. They can modify, delete, or access any files your user account can access. Review and test all hook commands before adding them to your configuration. | ||||
| 4170 | + | ||||
| 4171 | +### Workspace trust | ||||
| 4172 | + | ||||
| 4173 | +Claude Code checks workspace trust before it runs any hook from a settings file. What counts as trusted depends on the session type: | ||||
| 4174 | + | ||||
| 4175 | +* **Interactive session**: Claude Code holds back hooks from every settings file, including your own `~/.claude/settings.json`, until you accept the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder, or for a parent directory whose trust extends to it | ||||
| 4176 | +* **`-p` or SDK session**: Claude Code never shows the dialog and treats the folder as trusted, so hooks committed in a repository's `.claude/settings.json` run in a folder you've never trusted | ||||
| 4177 | + | ||||
| 4178 | +Before you script `claude -p` over a repository you didn't write, review its `.claude/` settings files, start with [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode), or [turn hooks off for that run](#disable-or-remove-hooks) with `--settings '{"disableAllHooks": true}'`. Frontmatter hooks in a project subagent follow a stricter rule than settings-file hooks. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) lists each kind of repository content by session type. | ||||
| 4179 | + | ||||
| 4180 | +### Security best practices | ||||
| 4181 | + | ||||
| 4182 | +Keep these practices in mind when writing hooks: | ||||
| 4183 | + | ||||
| 4184 | +* **Validate and sanitize inputs**: never trust input data blindly | ||||
| 4185 | +* **Always quote shell variables**: use `"$VAR"` not `$VAR` | ||||
| 4186 | +* **Block path traversal**: check for `..` in file paths | ||||
| 4187 | +* **Use absolute paths**: specify full paths for scripts. In exec form, use `${CLAUDE_PROJECT_DIR}` and the path needs no quoting. In shell form, wrap it in double quotes | ||||
| 4188 | +* **Skip sensitive files**: avoid `.env`, `.git/`, keys, etc. | ||||
| 4189 | + | ||||
| 4190 | +## Windows PowerShell tool | ||||
| 4191 | + | ||||
| 4192 | +On Windows, you can run individual hooks in PowerShell by setting `"shell": "powershell"` on a command hook. Claude Code auto-detects `pwsh.exe`, the PowerShell 7 and later executable, and falls back to `powershell.exe` for Windows PowerShell 5.1. | ||||
| 4193 | + | ||||
| 4194 | +```json theme={null} | ||||
| 4195 | +{ | ||||
| 4196 | + "hooks": { | ||||
| 4197 | + "PostToolUse": [ | ||||
| 4198 | + { | ||||
| 4199 | + "matcher": "Write", | ||||
| 4200 | + "hooks": [ | ||||
| 4201 | + { | ||||
| 4202 | + "type": "command", | ||||
| 4203 | + "shell": "powershell", | ||||
| 4204 | + "command": "Write-Host 'File written'" | ||||
| 4205 | + } | ||||
| 4206 | + ] | ||||
| 4207 | + } | ||||
| 4208 | + ] | ||||
| 4209 | + } | ||||
| 4210 | +} | ||||
| 4211 | +``` | ||||
| 4212 | + | ||||
| 4213 | +### Reference scripts by path in PowerShell hooks | ||||
| 4214 | + | ||||
| 4215 | +To reference the project root from a PowerShell shell-form command, write `${CLAUDE_PROJECT_DIR}` or `$env:CLAUDE_PROJECT_DIR`. Claude Code rewrites the `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`, and `${CLAUDE_PLUGIN_DATA}` placeholders in a PowerShell shell-form command to PowerShell's `${env:NAME}` form, whether the hook is defined in `settings.json`, a plugin, or a skill. PowerShell then resolves the value from the exported environment after parsing, so the placeholder works inside double-quoted strings but not inside single-quoted strings, where PowerShell never expands variables. | ||||
| 4216 | + | ||||
| 4217 | +Don't write the bare `$CLAUDE_PROJECT_DIR` spelling in a PowerShell hook. PowerShell parses it as an undefined local variable and resolves it to `$null`, which leaves the script path without its project-root prefix. Claude Code doesn't rewrite that form; it logs a warning in the [debug log](#debug-hooks) instead. | ||||
| 4218 | + | ||||
| 4219 | +The example below shows a `settings.json` hook that runs a project script with the `$env:` form: | ||||
| 4220 | + | ||||
| 4221 | +```json theme={null} | ||||
| 4222 | +{ | ||||
| 4223 | + "type": "command", | ||||
| 4224 | + "shell": "powershell", | ||||
| 4225 | + "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\"" | ||||
| 4226 | +} | ||||
| 4227 | +``` | ||||
| 4228 | + | ||||
| 4229 | +## Debug hooks | ||||
| 4230 | + | ||||
| 4231 | +Hook execution details are written to the debug log file. Start Claude Code with `claude --debug-file <path>` to write the log to a known location, or run `claude --debug` and read the log at `~/.claude/debug/<session-id>.txt`. The `--debug` flag doesn't print to the terminal. | ||||
| 4232 | + | ||||
| 4233 | +For example, a `PostToolUse` hook on `Write` whose command prints `hook-ran` produces entries like: | ||||
| 4234 | + | ||||
| 4235 | +```text theme={null} | ||||
| 4236 | +2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text | ||||
| 4237 | +2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran" | ||||
| 4238 | +``` | ||||
| 4239 | + | ||||
| 4240 | +To find a slow hook, search the log for `Hooks:` lines that end in a duration. In Claude Code v2.1.296 or later, each command hook on a tool event, `UserPromptSubmit`, `SessionStart`, `Stop`, and several other events leaves one when it finishes, whatever it printed. The line gives the event name, joined by a colon to the tool name or other value the hook matched on, then the hook's command in brackets, the plugin it came from if any, how the run ended, and how long it took, as in `Hooks: PostToolUse:Write [.claude/hooks/log-write.sh] finished with status 0 (31ms)`. A run can also end as `timed out after <N>ms`, `cancelled`, `moved to the background`, or `failed to start`. On some events, such as `Notification`, `SessionEnd`, and `PreCompact`, a command hook leaves a `completed with status` line without a duration instead. | ||||
| 4241 | + | ||||
| 4242 | +For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching. | ||||
| 4243 | + | ||||
| 4244 | +For troubleshooting common issues like hooks not firing, Stop hooks that keep blocking, or configuration errors, see [Limitations and troubleshooting](https://code.claude.com/docs/en/hooks-guide.md#limitations-and-troubleshooting) in the guide. For a broader diagnostic walkthrough covering `/context`, `/doctor`, and settings precedence, see [Debug your config](https://code.claude.com/docs/en/debug-your-config.md). | ||||
added
docs/claude-code-docs/memory.md
+664 −0
@@ -0,0 +1,664 @@ | |||||
| 1 | +> ## Documentation Index | ||||
| 2 | +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt | ||||
| 3 | +> Use this file to discover all available pages before exploring further. | ||||
| 4 | + | ||||
| 5 | +# How Claude remembers your project | ||||
| 6 | + | ||||
| 7 | +> Give Claude persistent instructions with CLAUDE.md or AGENTS.md files, and let Claude accumulate learnings automatically with auto memory. | ||||
| 8 | + | ||||
| 9 | +Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions: | ||||
| 10 | + | ||||
| 11 | +* **CLAUDE.md files**: instructions you write to give Claude persistent context. Claude can also read a repository's [`AGENTS.md` files](#agents-md) in place of CLAUDE.md | ||||
| 12 | +* **Auto memory**: notes Claude writes itself based on your corrections and preferences | ||||
| 13 | + | ||||
| 14 | +This page covers how to: | ||||
| 15 | + | ||||
| 16 | +* [Write and organize CLAUDE.md files](#claude-md-files) | ||||
| 17 | +* [Use an existing AGENTS.md](#agents-md) as your project instructions | ||||
| 18 | +* [Scope rules to specific file types](#organize-rules-with-claude/rules/) with `.claude/rules/` | ||||
| 19 | +* [Configure auto memory](#auto-memory) so Claude takes notes automatically | ||||
| 20 | +* [Troubleshoot](#troubleshoot-memory-issues) when instructions aren't being followed | ||||
| 21 | + | ||||
| 22 | +## CLAUDE.md vs auto memory | ||||
| 23 | + | ||||
| 24 | +Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a [PreToolUse hook](https://code.claude.com/docs/en/hooks-guide.md) instead. The more specific and concise your instructions, the more consistently Claude follows them. | ||||
| 25 | + | ||||
| 26 | +| | CLAUDE.md files | Auto memory | | ||||
| 27 | +| :- | :- | :- | | ||||
| 28 | +| **Who writes it** | You | Claude | | ||||
| 29 | +| **What it contains** | Instructions and rules | Learnings and patterns | | ||||
| 30 | +| **Scope** | Project, user, or org | Per repository, shared across worktrees | | ||||
| 31 | +| **Loaded into** | Every session | Every session (first 200 lines or 25KB) | | ||||
| 32 | +| **Use for** | Coding standards, workflows, project architecture | Your preferences, corrections you give Claude, project context Claude can't derive from the code | | ||||
| 33 | + | ||||
| 34 | +Use CLAUDE.md files when you want to guide Claude's behavior. Auto memory lets Claude learn from your corrections without manual effort. | ||||
| 35 | + | ||||
| 36 | +Subagents can also maintain their own auto memory. See [subagent configuration](https://code.claude.com/docs/en/sub-agents.md#enable-persistent-memory) for details. | ||||
| 37 | + | ||||
| 38 | +## CLAUDE.md files | ||||
| 39 | + | ||||
| 40 | +CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. You write these files in plain text; Claude reads them at the start of every session. If your repository uses `AGENTS.md` instead, see [AGENTS.md](#agents-md). | ||||
| 41 | + | ||||
| 42 | +### When to add to CLAUDE.md | ||||
| 43 | + | ||||
| 44 | +Treat CLAUDE.md as the place you write down what you'd otherwise re-explain. Add to it when: | ||||
| 45 | + | ||||
| 46 | +* Claude makes the same mistake a second time | ||||
| 47 | +* A code review catches something Claude should have known about this codebase | ||||
| 48 | +* You type the same correction or clarification into chat that you typed last session | ||||
| 49 | +* A new teammate would need the same context to be productive | ||||
| 50 | + | ||||
| 51 | +Keep it to facts Claude should hold in every session: build commands, conventions, project layout, "always do X" rules. If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a [skill](https://code.claude.com/docs/en/skills.md) or a [path-scoped rule](#organize-rules-with-claude/rules/) instead. The [extension overview](https://code.claude.com/docs/en/features-overview.md#build-your-setup-over-time) covers when to use each mechanism. | ||||
| 52 | + | ||||
| 53 | +### Choose where to put CLAUDE.md files | ||||
| 54 | + | ||||
| 55 | +CLAUDE.md files can live in several locations, each with a different scope. The table below lists them in load order, from broadest scope to most specific, so a project instruction appears in context after a user instruction. | ||||
| 56 | + | ||||
| 57 | +| Scope | Location | Purpose | Use case examples | Shared with | | ||||
| 58 | +| - | - | - | - | - | | ||||
| 59 | +| **Managed policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` • Linux and WSL: `/etc/claude-code/CLAUDE.md` • Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization | | ||||
| 60 | +| **User instructions** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Only you (all projects) | | ||||
| 61 | +| **Project instructions** | `./CLAUDE.md` or `./.claude/CLAUDE.md`. See [AGENTS.md](#agents-md) for when `./AGENTS.md` loads instead of or alongside them | Team-shared instructions for the project | Project architecture, coding standards, common workflows | Team members via source control | | ||||
| 62 | +| **Local instructions** | `./CLAUDE.local.md` | Personal project-specific preferences; add to `.gitignore` | Your sandbox URLs, preferred test data | Only you (current project) | | ||||
| 63 | + | ||||
| 64 | +CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch. Files in subdirectories load on demand. See [How CLAUDE.md files load](#how-claude-md-files-load) for when they load and the full resolution order. | ||||
| 65 | + | ||||
| 66 | +For large projects, you can break instructions into topic-specific files using [project rules](#organize-rules-with-claude/rules/). Rules let you scope instructions to specific file types or subdirectories. | ||||
| 67 | + | ||||
| 68 | +### Set up a project CLAUDE.md | ||||
| 69 | + | ||||
| 70 | +A project CLAUDE.md can be stored in either `./CLAUDE.md` or `./.claude/CLAUDE.md`. Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. These instructions are shared with your team through version control, so focus on project-level standards rather than personal preferences. To confirm the file loaded, run `/context` in a session and check the list under **Memory files**. | ||||
| 71 | + | ||||
| 72 | +> [!TIP] | ||||
| 73 | +> | ||||
| 74 | +> Run `/init` to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, `/init` suggests improvements rather than overwriting it. Refine from there with instructions Claude wouldn't discover on its own. | ||||
| 75 | +> | ||||
| 76 | +> For an interactive multi-phase flow instead, set the `CLAUDE_CODE_NEW_INIT` environment variable to `1` before you run `/init`. Set it in your shell or in the `env` block of a settings file, as shown in [Set environment variables](https://code.claude.com/docs/en/env-vars.md#set-environment-variables). With it set, `/init` asks which artifacts to set up: CLAUDE.md files, skills, and hooks. It then explores your codebase with a subagent, fills in gaps via follow-up questions, and presents a reviewable proposal before writing any files. The variable only changes how `/init` runs, so you can leave it set. | ||||
| 77 | + | ||||
| 78 | +### Write effective instructions | ||||
| 79 | + | ||||
| 80 | +Claude treats CLAUDE.md files as context, not enforced configuration, so how you write instructions affects how reliably Claude follows them. Write instructions that are concrete enough to verify: | ||||
| 81 | + | ||||
| 82 | +* "Use 2-space indentation" instead of "Format code properly" | ||||
| 83 | +* "Run `npm test` before committing" instead of "Test your changes" | ||||
| 84 | +* "API handlers live in `src/api/handlers/`" instead of "Keep files organized" | ||||
| 85 | + | ||||
| 86 | +Keep your files short, organized, and consistent: | ||||
| 87 | + | ||||
| 88 | +* **Size**: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. Move instructions that matter for only part of the codebase into [path-scoped rules](#path-specific-rules), which load only when Claude works with matching files. [Imports](#import-additional-files) help you organize a long file but don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them. | ||||
| 89 | +* **Structure**: group related instructions under markdown headers and bullets. Organized sections are easier for Claude to follow than dense paragraphs. | ||||
| 90 | +* **Consistency**: if two instructions contradict each other, Claude may pick one arbitrarily. Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and [`.claude/rules/`](#organize-rules-with-claude/rules/) periodically to remove outdated or conflicting instructions. To have Claude find them for you, [run a prompt audit](#audit-your-instruction-files). | ||||
| 91 | + | ||||
| 92 | +#### Audit your instruction files | ||||
| 93 | + | ||||
| 94 | +To have Claude check your instruction files for outdated or conflicting content, run `/doctor prompt-audit` in a session. Claude looks for problems such as instructions written for older models, references to files or commands that don't exist, and files that contradict each other. You get a report of findings with proposed edits, and nothing in your files changes until you ask Claude to apply them. | ||||
| 95 | + | ||||
| 96 | +By default, the audit covers your CLAUDE.md, CLAUDE.local.md, and AGENTS.md files, plus the rules, skills, commands, subagents, and output styles under `.claude/` and `~/.claude/`. To audit one file or directory instead, pass its path, for example `/doctor prompt-audit .claude/skills/deploy`. | ||||
| 97 | + | ||||
| 98 | +The audit runs through the bundled `/claude-api` skill. It's unavailable while that skill is turned off in [`skillOverrides`](https://code.claude.com/docs/en/skills#override-skill-visibility-from-settings) or with [`disableBundledSkills`](https://code.claude.com/docs/en/settings-reference#disablebundledskills). `/doctor prompt-audit` requires Claude Code v2.1.283 or later. | ||||
| 99 | + | ||||
| 100 | +### Import additional files | ||||
| 101 | + | ||||
| 102 | +CLAUDE.md files can import additional files using `@path/to/import` syntax. Imported files are expanded and loaded into context alongside the CLAUDE.md that references them. | ||||
| 103 | + | ||||
| 104 | +Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. Imported files can recursively import other files, with a maximum depth of four hops. | ||||
| 105 | + | ||||
| 106 | +To import a file whose path contains spaces, put a backslash before each space. Without the backslashes, the path ends at the first space, even when the import is on a line of its own. A path wrapped in quotes isn't imported at all, with or without the backslashes. This import loads a file from a folder named `Design Docs`: | ||||
| 107 | + | ||||
| 108 | +```text theme={null} | ||||
| 109 | +- API conventions @Design\ Docs/api-conventions.md | ||||
| 110 | +``` | ||||
| 111 | + | ||||
| 112 | +Import parsing skips Markdown code spans and fenced code blocks. To mention a path in your CLAUDE.md without importing it, wrap it in backticks: writing `` `@README` `` keeps the text literal, while `@README` outside backticks imports the file. | ||||
| 113 | + | ||||
| 114 | +To pull in a README, package.json, and a workflow guide, reference them with `@` syntax anywhere in your CLAUDE.md: | ||||
| 115 | + | ||||
| 116 | +```text theme={null} | ||||
| 117 | +See @README for project overview and @package.json for available npm commands for this project. | ||||
| 118 | + | ||||
| 119 | +# Additional Instructions | ||||
| 120 | +- git workflow @docs/git-instructions.md | ||||
| 121 | +``` | ||||
| 122 | + | ||||
| 123 | +For private per-project preferences that shouldn't be checked into version control, create a `CLAUDE.local.md` at the project root. It loads alongside `CLAUDE.md` and is treated the same way. Add `CLAUDE.local.md` to your `.gitignore` so it isn't committed. With `CLAUDE_CODE_NEW_INIT=1` set, running `/init` and choosing the personal option does this for you. | ||||
| 124 | + | ||||
| 125 | +If you work across multiple git worktrees of the same repository, a gitignored `CLAUDE.local.md` only exists in the worktree where you created it. To share personal instructions across worktrees, import a file from your home directory instead: | ||||
| 126 | + | ||||
| 127 | +```text theme={null} | ||||
| 128 | +# Individual Preferences | ||||
| 129 | +- @~/.claude/my-project-instructions.md | ||||
| 130 | +``` | ||||
| 131 | + | ||||
| 132 | +> [!WARNING] | ||||
| 133 | +> | ||||
| 134 | +> An import in a project-level memory file is external when its path resolves outside your working directory, like the home directory import above. The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog doesn't appear again. | ||||
| 135 | +> | ||||
| 136 | +> Claude Code shows the dialog to protect you from files other people commit to a shared project. User-scope memory files, such as `~/.claude/CLAUDE.md` and `~/.claude/rules/`, are files you wrote yourself. Except in [Cowork](https://claude.com/product/cowork) sessions on your desktop, Claude Code loads their imports without the dialog and trusts them like the rest of your personal configuration. | ||||
| 137 | +> | ||||
| 138 | +> In Cowork sessions on your desktop, Claude Code skips any import in a user-scope file that resolves to a path outside the session's working directory and loads the rest of the file. In those sessions it also skips a `~/.claude/CLAUDE.md` that is itself a symlink or hard link, and a symlinked `~/.claude/rules/` directory or rule file that points outside the working directory. | ||||
| 139 | + | ||||
| 140 | +### How CLAUDE.md files load | ||||
| 141 | + | ||||
| 142 | +Claude Code loads `CLAUDE.md` and `CLAUDE.local.md` from your current working directory and every directory above it. Run Claude Code in `foo/bar/` and it loads instructions from `foo/bar/CLAUDE.md`, `foo/CLAUDE.md`, and any `CLAUDE.local.md` files alongside them. | ||||
| 143 | + | ||||
| 144 | +All discovered files are concatenated into context rather than overriding each other. Across the directory tree, content is ordered from the filesystem root down to your working directory. For the `foo/bar/` example, `foo/CLAUDE.md` appears in context before `foo/bar/CLAUDE.md`, so instructions closer to where you launched Claude are read last. Within each directory, `CLAUDE.local.md` is appended after `CLAUDE.md`, so your personal notes are the last thing Claude reads at that level. | ||||
| 145 | + | ||||
| 146 | +Claude also discovers `CLAUDE.md` and `CLAUDE.local.md` files in subdirectories under your current working directory. Instead of loading them at launch, Claude Code loads each one once Claude reads, writes, or edits another file in that subdirectory. Reading includes viewing the file with a Bash command that [counts as a read](https://code.claude.com/docs/en/tools-reference.md#edit-tool-behavior), such as `cat` or `head` on a single file. For files inside a worktree under `.claude/worktrees/`, see [Isolate subagents with worktrees](https://code.claude.com/docs/en/worktrees.md#isolate-subagents-with-worktrees). | ||||
| 147 | + | ||||
| 148 | +If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) to skip them. For the full layout of root and per-directory CLAUDE.md files and rules, see [Monorepos and large repos](https://code.claude.com/docs/en/large-codebases.md). | ||||
| 149 | + | ||||
| 150 | +Block-level HTML comments (`<!-- maintainer notes -->`) in CLAUDE.md files are stripped before the content is injected into Claude's context. Use them to leave notes for human maintainers without spending context tokens on them. Comments inside code blocks are preserved. When you open a CLAUDE.md file directly with the Read tool, comments remain visible. | ||||
| 151 | + | ||||
| 152 | +#### Load from additional directories | ||||
| 153 | + | ||||
| 154 | +The `--add-dir` flag gives Claude access to additional directories outside your main working directory. By default, CLAUDE.md files from these directories are not loaded. | ||||
| 155 | + | ||||
| 156 | +To also load memory files from additional directories, set the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` environment variable: | ||||
| 157 | + | ||||
| 158 | +```bash theme={null} | ||||
| 159 | +CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config | ||||
| 160 | +``` | ||||
| 161 | + | ||||
| 162 | +The inline form sets the variable for that one launch in Bash or Zsh. To keep it on for every session, add it to the `env` block in `~/.claude/settings.json` as shown in [Set environment variables](https://code.claude.com/docs/en/env-vars.md#set-environment-variables). | ||||
| 163 | + | ||||
| 164 | +This loads `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, and `CLAUDE.local.md` from the additional directory. `CLAUDE.local.md` is skipped if you exclude `local` from [`--setting-sources`](https://code.claude.com/docs/en/cli-reference). | ||||
| 165 | + | ||||
| 166 | +### Organize rules with `.claude/rules/` | ||||
| 167 | + | ||||
| 168 | +For larger projects, you can organize instructions into multiple files using the `.claude/rules/` directory. This keeps instructions modular and easier for teams to maintain. Rules can also be [scoped to specific file paths](#path-specific-rules), so they only load into context when Claude works with matching files, reducing noise and saving context space. | ||||
| 169 | + | ||||
| 170 | +> [!NOTE] | ||||
| 171 | +> | ||||
| 172 | +> Rules load into context every session or when matching files are opened. For task-specific instructions that don't need to be in context all the time, use [skills](https://code.claude.com/docs/en/skills.md) instead, which only load when you invoke them or when Claude determines they're relevant to your prompt. | ||||
| 173 | + | ||||
| 174 | +#### Set up rules | ||||
| 175 | + | ||||
| 176 | +Place markdown files in your project's `.claude/rules/` directory. Each file should cover one topic, with a descriptive filename like `testing.md` or `api-design.md`. All `.md` files are discovered recursively, so you can organize rules into subdirectories like `frontend/` or `backend/`: | ||||
| 177 | + | ||||
| 178 | +```text theme={null} | ||||
| 179 | +your-project/ | ||||
| 180 | +├── .claude/ | ||||
| 181 | +│ ├── CLAUDE.md # Main project instructions | ||||
| 182 | +│ └── rules/ | ||||
| 183 | +│ ├── code-style.md # Code style guidelines | ||||
| 184 | +│ ├── testing.md # Testing conventions | ||||
| 185 | +│ └── security.md # Security requirements | ||||
| 186 | +``` | ||||
| 187 | + | ||||
| 188 | +Rules without [`paths` frontmatter](#path-specific-rules) are loaded at launch with the same priority as `.claude/CLAUDE.md`. | ||||
| 189 | + | ||||
| 190 | +Project rules are skipped if you exclude `project` from [`--setting-sources`](https://code.claude.com/docs/en/cli-reference). Before v2.1.211, rules that load on demand, including path-scoped rules and rules in nested `.claude/rules/` directories, loaded even when `project` was excluded. | ||||
| 191 | + | ||||
| 192 | +#### Path-specific rules | ||||
| 193 | + | ||||
| 194 | +Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns. | ||||
| 195 | + | ||||
| 196 | +```markdown theme={null} | ||||
| 197 | +--- | ||||
| 198 | +paths: | ||||
| 199 | + - "src/api/**/*.ts" | ||||
| 200 | +--- | ||||
| 201 | + | ||||
| 202 | +# API Development Rules | ||||
| 203 | + | ||||
| 204 | +- All API endpoints must include input validation | ||||
| 205 | +- Use the standard error response format | ||||
| 206 | +- Include OpenAPI documentation comments | ||||
| 207 | +``` | ||||
| 208 | + | ||||
| 209 | +Rules without a `paths` field are loaded unconditionally and apply to all files. A path-scoped rule loads when Claude uses the Read, Write, or Edit tool on a matching file. It also loads when Claude views a matching file with a Bash command that [counts as a read](https://code.claude.com/docs/en/tools-reference.md#edit-tool-behavior), such as `cat` or `head` on a single file. Matching also works when Claude reaches a file through a symlinked path to the project directory, for example in a symlinked checkout. | ||||
| 210 | + | ||||
| 211 | +Each pattern is relative to the rule's base directory: | ||||
| 212 | + | ||||
| 213 | +* **Project rules**: the directory that contains the rule's `.claude` folder | ||||
| 214 | +* **[User-level rules](#user-level-rules)**: the session's [primary working directory](https://code.claude.com/docs/en/permissions.md#working-directories) | ||||
| 215 | + | ||||
| 216 | +To have path-scoped rules load for files in a sibling git worktree, start Claude Code in that worktree or [move the session there with `/cd`](https://code.claude.com/docs/en/permissions#move-the-session-to-another-directory). | ||||
| 217 | + | ||||
| 218 | +Use glob patterns in the `paths` field to match files by extension, directory, or any combination: | ||||
| 219 | + | ||||
| 220 | +| Pattern | Matches | | ||||
| 221 | +| - | - | | ||||
| 222 | +| `**/*.ts` | All TypeScript files in any directory | | ||||
| 223 | +| `src/**/*` | All files under `src/` directory | | ||||
| 224 | +| `*.md` | Markdown files in the project root | | ||||
| 225 | +| `src/components/*.tsx` | React components in a specific directory | | ||||
| 226 | + | ||||
| 227 | +You can specify multiple patterns and use brace expansion to match multiple extensions in one pattern: | ||||
| 228 | + | ||||
| 229 | +```markdown theme={null} | ||||
| 230 | +--- | ||||
| 231 | +paths: | ||||
| 232 | + - "src/**/*.{ts,tsx}" | ||||
| 233 | + - "lib/**/*.ts" | ||||
| 234 | + - "tests/**/*.test.ts" | ||||
| 235 | +--- | ||||
| 236 | +``` | ||||
| 237 | + | ||||
| 238 | +Each brace group multiplies the number of expanded patterns: `src/*.{ts,tsx}` expands to two patterns, and `{a,b}/{c,d}/*.{ts,tsx}` to eight. To keep expansion bounded, a rule's whole `paths` list shares one budget of 1,000 expanded patterns and 4 MiB, and patterns without braces don't count against it. | ||||
| 239 | + | ||||
| 240 | +Claude Code uses any pattern that would exceed the budget unexpanded, and its literal braces match no files. | ||||
| 241 | + | ||||
| 242 | +Glob syntax treats `[` as the start of a bracket expression such as `[abc]`. A pattern with a `[` that can't be read as a bracket expression, such as `photos [2024/**`, is invalid: it matches nothing, and the rule's other patterns keep working. To match a literal `[` in a file name, escape it as `photos \[2024/**`. | ||||
| 243 | + | ||||
| 244 | +#### Rule frontmatter reference | ||||
| 245 | + | ||||
| 246 | +Configure a rule with YAML [frontmatter](https://code.claude.com/docs/en/glossary.md#frontmatter) between `---` markers at the top of the file. `paths` is the only field Claude Code reads from a rule; any other field is ignored without an error. Claude Code removes the frontmatter before loading the rule into context. | ||||
| 247 | + | ||||
| 248 | +| Field | Required | Description | | ||||
| 249 | +| :- | :- | :- | | ||||
| 250 | +| `paths` | No | Glob patterns that [scope the rule to matching files](#path-specific-rules). Accepts a YAML list or a comma-separated string | | ||||
| 251 | + | ||||
| 252 | +If the YAML between the markers doesn't parse, Claude Code ignores the frontmatter and loads the rule as if it had no `paths`. Run `claude --debug` to see the parse error. | ||||
| 253 | + | ||||
| 254 | +#### Share rules across projects with symlinks | ||||
| 255 | + | ||||
| 256 | +The `.claude/rules/` directory supports symlinks, so you can maintain a shared set of rules and link them into multiple projects. Circular symlinks are detected and handled gracefully. | ||||
| 257 | + | ||||
| 258 | +Claude Code treats a symlink whose target is outside your working directory like an [external import](#import-additional-files). The linked rules don't load until you approve external imports for the project, and after that only the ones without a [`paths` field](#path-specific-rules) load. | ||||
| 259 | + | ||||
| 260 | +Claude Code asks for that approval once per project, in a dialog at the start of an interactive session. The dialog lists the linked rule files alongside any external `@path` imports. To load shared rules without that approval, keep them in [`~/.claude/rules/`](#user-level-rules), where they apply to every project on your machine. | ||||
| 261 | + | ||||
| 262 | +This example links both a shared directory and an individual file: | ||||
| 263 | + | ||||
| 264 | +```bash theme={null} | ||||
| 265 | +ln -s ~/shared-claude-rules .claude/rules/shared | ||||
| 266 | +ln -s ~/company-standards/security.md .claude/rules/security.md | ||||
| 267 | +``` | ||||
| 268 | + | ||||
| 269 | +If you point a `.claude/rules/` or `CLAUDE.md` symlink at a network path such as the UNC share `\\server\share` or a path under `/net` or `/Network`, the linked instructions don't load. Claude Code doesn't follow the link, because looking up such a path can contact the host it names. `\\wsl$` paths don't count as network paths. | ||||
| 270 | + | ||||
| 271 | +#### User-level rules | ||||
| 272 | + | ||||
| 273 | +Personal rules in `~/.claude/rules/` apply to every project on your machine. Use them for preferences that aren't project-specific: | ||||
| 274 | + | ||||
| 275 | +```text theme={null} | ||||
| 276 | +~/.claude/rules/ | ||||
| 277 | +├── preferences.md # Your personal coding preferences | ||||
| 278 | +└── workflows.md # Your preferred workflows | ||||
| 279 | +``` | ||||
| 280 | + | ||||
| 281 | +Claude Code loads user-level rules before project rules, so a project rule appears later in Claude's context than a user rule. Neither set overrides the other: if a user rule and a project rule conflict, Claude may follow either one, so keep the two consistent. | ||||
| 282 | + | ||||
| 283 | +### Manage CLAUDE.md for large teams | ||||
| 284 | + | ||||
| 285 | +For organizations deploying Claude Code across teams, you can centralize instructions and control which CLAUDE.md files are loaded. | ||||
| 286 | + | ||||
| 287 | +#### Deploy organization-wide CLAUDE.md | ||||
| 288 | + | ||||
| 289 | +Organizations can deploy a centrally managed CLAUDE.md that applies to all users on a machine. Developers can [exclude other CLAUDE.md files](#exclude-specific-claude-md-files) with the `claudeMdExcludes` setting, but not this one. If a developer starts a session with CLAUDE.md loading turned off altogether, that session doesn't load the managed content either. Use the file for guidance, and enforce rules with [managed settings](https://code.claude.com/docs/en/managed-settings.md) such as `permissions.deny`. | ||||
| 290 | + | ||||
| 291 | +**1. Create the file at the managed policy location** | ||||
| 292 | + | ||||
| 293 | +* macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` | ||||
| 294 | +* Linux and WSL: `/etc/claude-code/CLAUDE.md` | ||||
| 295 | +* Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | ||||
| 296 | + | ||||
| 297 | +**2. Deploy with your configuration management system** | ||||
| 298 | + | ||||
| 299 | +Use MDM, Group Policy, Ansible, or similar tools to distribute the file across developer machines. See [managed settings](https://code.claude.com/docs/en/managed-settings.md) for other organization-wide configuration options. | ||||
| 300 | + | ||||
| 301 | +The `claudeMd` key lets you put managed CLAUDE.md content directly inside `managed-settings.json` instead of deploying a separate file. | ||||
| 302 | + | ||||
| 303 | +**Scope**: all users on the machine, in any repository. For repository-specific guidance, commit a project CLAUDE.md instead. | ||||
| 304 | + | ||||
| 305 | +**Precedence**: same as a managed CLAUDE.md file. Loads before user and project CLAUDE.md. | ||||
| 306 | + | ||||
| 307 | +**Where it's honored**: managed and policy settings only. Setting `claudeMd` in user, project, or local settings has no effect. | ||||
| 308 | + | ||||
| 309 | +The example below adds behavioral instructions directly in a managed settings file: | ||||
| 310 | + | ||||
| 311 | +```json theme={null} | ||||
| 312 | +{ | ||||
| 313 | + "claudeMd": "Always run `make lint` before committing.\nNever push directly to main." | ||||
| 314 | +} | ||||
| 315 | +``` | ||||
| 316 | + | ||||
| 317 | +A managed CLAUDE.md and [managed settings](https://code.claude.com/docs/en/managed-settings.md) serve different purposes. Use settings for technical enforcement and CLAUDE.md for behavioral guidance: | ||||
| 318 | + | ||||
| 319 | +| Concern | Configure in | | ||||
| 320 | +| :- | :- | | ||||
| 321 | +| Block specific tools, commands, or file paths | Managed settings: `permissions.deny` | | ||||
| 322 | +| Enforce sandbox isolation | Managed settings: `sandbox.enabled` | | ||||
| 323 | +| Environment variables and API provider routing | Managed settings: `env` | | ||||
| 324 | +| Login method and organization restrictions | Managed settings: `forceLoginMethod`, `forceLoginOrgUUID` | | ||||
| 325 | +| Code style and quality guidelines | Managed CLAUDE.md | | ||||
| 326 | +| Data handling and compliance reminders | Managed CLAUDE.md | | ||||
| 327 | +| Behavioral instructions for Claude | Managed CLAUDE.md | | ||||
| 328 | + | ||||
| 329 | +Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer. | ||||
| 330 | + | ||||
| 331 | +#### Exclude specific CLAUDE.md files | ||||
| 332 | + | ||||
| 333 | +In large monorepos, ancestor CLAUDE.md files may contain instructions that aren't relevant to your work. The `claudeMdExcludes` setting lets you skip specific files by path or glob pattern. You can't exclude a [managed CLAUDE.md file](#deploy-organization-wide-claude-md) with `claudeMdExcludes`. | ||||
| 334 | + | ||||
| 335 | +This example excludes a top-level CLAUDE.md and a rules directory from a parent folder. Add it to `.claude/settings.local.json` so the exclusion stays local to your machine: | ||||
| 336 | + | ||||
| 337 | +```json theme={null} | ||||
| 338 | +{ | ||||
| 339 | + "claudeMdExcludes": [ | ||||
| 340 | + "**/monorepo/CLAUDE.md", | ||||
| 341 | + "/home/user/monorepo/other-team/.claude/rules/**" | ||||
| 342 | + ] | ||||
| 343 | +} | ||||
| 344 | +``` | ||||
| 345 | + | ||||
| 346 | +Patterns are matched against absolute file paths using glob syntax. You can configure `claudeMdExcludes` at any [settings layer](https://code.claude.com/docs/en/settings.md#where-settings-live): user, project, local, or managed policy. Arrays merge across layers. | ||||
| 347 | + | ||||
| 348 | +To exclude a rules file you reach through a [symlink](#share-rules-across-projects-with-symlinks), whether the file or its directory is the link, write the pattern against either path: the file's path under `.claude/rules/` or its link target. A pattern that matches either path excludes the file. Before v2.1.239, only a pattern that matched the link target excluded the file. | ||||
| 349 | + | ||||
| 350 | +## AGENTS.md | ||||
| 351 | + | ||||
| 352 | +Claude Code can read [`AGENTS.md`](https://code.claude.com/docs/en/glossary#agents-md) as your project instructions, so a repository already set up for other coding agents works without adding a `CLAUDE.md`, an import, or a setting. This table shows what Claude reads by default for each combination of instruction files in your repository: | ||||
| 353 | + | ||||
| 354 | +| Your repository has | Claude reads | | ||||
| 355 | +| :- | :- | | ||||
| 356 | +| An `AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `AGENTS.md` | | ||||
| 357 | +| An `AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `CLAUDE.md` files only | | ||||
| 358 | +| A `CLAUDE.md` that already [imports `AGENTS.md`](#share-one-file-with-other-coding-tools) | Your `CLAUDE.md`, with `AGENTS.md` included through the import | | ||||
| 359 | + | ||||
| 360 | +To change the default, for example to have Claude always read both files, read only `CLAUDE.md`, or read only your organization's managed instructions, [change the **Project instructions** setting](#choose-which-instruction-files-load). | ||||
| 361 | + | ||||
| 362 | +> [!NOTE] | ||||
| 363 | +> | ||||
| 364 | +> Reading `AGENTS.md` directly requires Claude Code v2.1.277 or later. In some sessions Claude [can't read `AGENTS.md`](#when-agents-md-support-is-unavailable), so [import it from a `CLAUDE.md`](#share-one-file-with-other-coding-tools) there instead. | ||||
| 365 | + | ||||
| 366 | +### When Claude Code reads AGENTS.md | ||||
| 367 | + | ||||
| 368 | +By default, Claude reads `AGENTS.md` only when you have no `CLAUDE.md` in your working directory or above it. Here's which of your files count for that check: | ||||
| 369 | + | ||||
| 370 | +* **Count, so Claude reads them instead of `AGENTS.md`**: a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in your working directory or any directory above it | ||||
| 371 | +* **Don't count, and keep loading alongside `AGENTS.md`**: your `~/.claude/CLAUDE.md`, your organization's managed `CLAUDE.md`, and `.claude/rules/` files | ||||
| 372 | + | ||||
| 373 | +When none count, here's what Claude reads and how you can tell: | ||||
| 374 | + | ||||
| 375 | +* **At session start**: every `AGENTS.md` and `.claude/AGENTS.md` in your working directory and the directories above it. In an interactive session you see a line such as `no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md` in the conversation | ||||
| 376 | +* **As Claude works in subdirectories**: a subdirectory's `AGENTS.md`, when Claude opens a file there with the Read tool and that subdirectory has none of the three `CLAUDE.md` files of its own | ||||
| 377 | +* **Inside each `AGENTS.md`**: [`@path` imports](#import-additional-files) are expanded, [`claudeMdExcludes`](#exclude-specific-claude-md-files) patterns apply, and subagents that [start without project instructions](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup) start without these files too | ||||
| 378 | +* **Not read**: `AGENTS.local.md`, `AGENTS.override.md`, or anything under a `.agents/` directory | ||||
| 379 | + | ||||
| 380 | +> [!NOTE] | ||||
| 381 | +> | ||||
| 382 | +> Because `CLAUDE.local.md` counts, adding one to keep your own uncommitted instructions in a project that relies on `AGENTS.md` stops Claude from reading `AGENTS.md` for you. To keep your `CLAUDE.local.md` and still have Claude read `AGENTS.md`, set **Project instructions** to [`claude-md-and-agents-md`](#choose-which-instruction-files-load). | ||||
| 383 | + | ||||
| 384 | +### Choose which instruction files load | ||||
| 385 | + | ||||
| 386 | +To change which files Claude reads, type `/config` in a Claude Code session to open the settings panel, then set **Project instructions** to one of these values: | ||||
| 387 | + | ||||
| 388 | +| Value | What Claude reads | | ||||
| 389 | +| :- | :- | | ||||
| 390 | +| `claude-md-or-agents-md` | Your `CLAUDE.md` files, or your `AGENTS.md` files when you have no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. This is the default | | ||||
| 391 | +| `claude-md-and-agents-md` | Your `CLAUDE.md` and `AGENTS.md` files together, each directory's `CLAUDE.md` files first and its `AGENTS.md` after them. Claude Code skips an `AGENTS.md` it has already loaded, so one that your `CLAUDE.md` imports or symlinks to isn't read twice | | ||||
| 392 | +| `claude-md` | Your `CLAUDE.md` files only | | ||||
| 393 | +| `managed-only` | Only your organization's managed `CLAUDE.md` and [auto memory](#auto-memory) at launch. Your project, local, and user `CLAUDE.md` files, your `.claude/rules/` files, and every `AGENTS.md` are left out. A subdirectory's `CLAUDE.md` and `.claude/rules/` files, and [path-scoped rules](#path-specific-rules), still load on demand | | ||||
| 394 | + | ||||
| 395 | +You can also set the value in a settings file instead of `/config`. Add it to [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs) under `cc-plugin-agents-md@builtin`, the ID of the built-in plugin that reads `AGENTS.md`. Claude Code reads the entry from `~/.claude/settings.json`, a `--settings` file, or [managed settings](https://code.claude.com/docs/en/managed-settings.md), and ignores it in project and local settings files. This example has Claude read both files: | ||||
| 396 | + | ||||
| 397 | +```json settings.json theme={null} | ||||
| 398 | +{ | ||||
| 399 | + "pluginConfigs": { | ||||
| 400 | + "cc-plugin-agents-md@builtin": { | ||||
| 401 | + "options": { "instructionFiles": "claude-md-and-agents-md" } | ||||
| 402 | + } | ||||
| 403 | + } | ||||
| 404 | +} | ||||
| 405 | +``` | ||||
| 406 | + | ||||
| 407 | +Before v2.1.285, the plugin's ID was `agents-md@builtin`, and Claude Code ignored an entry under `cc-plugin-agents-md@builtin`. If earlier versions also read your settings file, use `agents-md@builtin` there. Claude Code v2.1.285 and later reads an entry under either ID. | ||||
| 408 | + | ||||
| 409 | +Your change applies from the next message you send and in every new session. | ||||
| 410 | + | ||||
| 411 | +### When AGENTS.md support is unavailable | ||||
| 412 | + | ||||
| 413 | +In these sessions Claude reads `CLAUDE.md` files only, and **Project instructions** doesn't appear in the `/config` settings panel: | ||||
| 414 | + | ||||
| 415 | +* You're on a Claude Code version before v2.1.277 | ||||
| 416 | +* You used `/plugin` to disable the built-in plugin that reads `AGENTS.md` | ||||
| 417 | +* In some cases, it's your [first session after you upgrade](https://code.claude.com/docs/en/env-vars.md#first-session-after-an-install-or-upgrade) from v2.1.276 or earlier. Claude reads `AGENTS.md` from your next session on | ||||
| 418 | + | ||||
| 419 | +Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read `CLAUDE.md` files only. On those versions, update Claude Code. To give Claude your `AGENTS.md` in any of these sessions, [import it from a `CLAUDE.md`](#share-one-file-with-other-coding-tools). | ||||
| 420 | + | ||||
| 421 | +### Where AGENTS.md differs from CLAUDE.md | ||||
| 422 | + | ||||
| 423 | +An `AGENTS.md` that Claude reads through the **Project instructions** setting differs from a `CLAUDE.md` in these places: | ||||
| 424 | + | ||||
| 425 | +| | `CLAUDE.md` | `AGENTS.md` read through the setting | | ||||
| 426 | +| :- | :- | :- | | ||||
| 427 | +| [`InstructionsLoaded` hooks](https://code.claude.com/docs/en/hooks#instructionsloaded) | Fire | Don't fire. They fire as usual for an `AGENTS.md` that a `CLAUDE.md` imports or symlinks to | | ||||
| 428 | +| Directories you add with `--add-dir` while [`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD`](#load-from-additional-directories) is set | Their `CLAUDE.md` loads | Their `AGENTS.md` doesn't load | | ||||
| 429 | +| An `@path` import of a file outside your working directory | Claude Code asks you to approve [external imports](#import-additional-files) | Loads only if you already approved external imports for this project, with no prompt | | ||||
| 430 | + | ||||
| 431 | +### Remove an earlier AGENTS.md workaround | ||||
| 432 | + | ||||
| 433 | +If you set Claude Code up to read `AGENTS.md` before it did so on its own, here's what to do with each common setup: | ||||
| 434 | + | ||||
| 435 | +* **A `CLAUDE.md` containing `@AGENTS.md`**: you can leave it. Keeping the import never makes Claude read `AGENTS.md` twice, whichever **Project instructions** value you use. Remove the `CLAUDE.md` if it holds nothing else, or keep it if some of your sessions [can't load `AGENTS.md` directly](#when-agents-md-support-is-unavailable). | ||||
| 436 | +* **A `CLAUDE.md` that tells Claude in words to read `AGENTS.md`**: Claude sees `AGENTS.md` only if it decides to open the file. Delete the `CLAUDE.md` so Claude reads `AGENTS.md` directly, or replace the sentence with an `@AGENTS.md` import. | ||||
| 437 | +* **A `CLAUDE.md` symlinked to `AGENTS.md`**: nothing, or delete the symlink. Either way Claude reads the content once. | ||||
| 438 | +* **A `SessionStart` hook that prints `AGENTS.md`**: remove it. Once Claude reads `AGENTS.md` directly, the hook adds a second copy to the context. | ||||
| 439 | + | ||||
| 440 | +### Share one file with other coding tools | ||||
| 441 | + | ||||
| 442 | +When Claude isn't reading your `AGENTS.md` directly, you can still keep it as the one file every tool shares by putting an `@AGENTS.md` import in a `CLAUDE.md` next to it. Do this when your project also has a `CLAUDE.md`, when you've set **Project instructions** to `claude-md`, or in sessions that [can't load `AGENTS.md`](#when-agents-md-support-is-unavailable). Add any Claude-specific instructions below the import, and Claude reads the imported file first, then the rest: | ||||
| 443 | + | ||||
| 444 | +```markdown CLAUDE.md theme={null} | ||||
| 445 | +@AGENTS.md | ||||
| 446 | + | ||||
| 447 | +## Claude Code | ||||
| 448 | + | ||||
| 449 | +Use plan mode for changes under `src/billing/`. | ||||
| 450 | +``` | ||||
| 451 | + | ||||
| 452 | +If you don't need Claude-specific content, a symlink also works: | ||||
| 453 | + | ||||
| 454 | +```bash theme={null} | ||||
| 455 | +ln -s AGENTS.md CLAUDE.md | ||||
| 456 | +``` | ||||
| 457 | + | ||||
| 458 | +The command prints no output on success. Before you choose the symlink over the import, check these constraints: | ||||
| 459 | + | ||||
| 460 | +* **Editing**: Claude reads `CLAUDE.md` through the link, but the Edit and Write tools [refuse to write through a symlink](https://code.claude.com/docs/en/errors.md#refusing-after-a-symlink-changed), and the refusal directs Claude to edit the link's target, `AGENTS.md`, instead | ||||
| 461 | +* **Windows**: if you or anyone who clones the repository works on Windows, use the `@AGENTS.md` import instead. Creating a symlink there needs Administrator privileges or Developer Mode, and Git checks a committed symlink out as a plain text file unless `core.symlinks` is enabled, which leaves that clone with a one-line `CLAUDE.md` in place of your instructions | ||||
| 462 | + | ||||
| 463 | +With either approach, run `/context` in your next session and confirm `CLAUDE.md` appears under **Memory files**. | ||||
| 464 | + | ||||
| 465 | +### Migrate instructions from other tools | ||||
| 466 | + | ||||
| 467 | +Running [`/init`](https://code.claude.com/docs/en/commands) reads other tools' instruction files and incorporates the relevant parts into the generated `CLAUDE.md`: | ||||
| 468 | + | ||||
| 469 | +* Cursor rules in `.cursor/rules/` or `.cursorrules` | ||||
| 470 | +* Copilot rules in `.github/copilot-instructions.md` | ||||
| 471 | +* With `CLAUDE_CODE_NEW_INIT=1` set: `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` or `.windsurfrules`, and `.clinerules` | ||||
| 472 | + | ||||
| 473 | +You can also run [`/import`](https://code.claude.com/docs/en/commands) to bring a supported coding agent's configuration into Claude Code, which appends a one-time copy of instruction files such as `AGENTS.md` to the matching `CLAUDE.md` and carries over MCP servers, commands, subagents, and skills. | ||||
| 474 | + | ||||
| 475 | +## Auto memory | ||||
| 476 | + | ||||
| 477 | +Auto memory lets Claude accumulate knowledge across sessions without you writing anything. As it works, Claude saves four kinds of notes for itself. Claude records the kind as a `type` field in the memory file's frontmatter: | ||||
| 478 | + | ||||
| 479 | +* `user`: your role, expertise, and working preferences | ||||
| 480 | +* `feedback`: corrections you give Claude and approaches you confirm | ||||
| 481 | +* `project`: ongoing work, deadlines, and decisions that Claude can't derive from the code or git history | ||||
| 482 | +* `reference`: where to find information outside the project, such as an issue tracker or dashboard | ||||
| 483 | + | ||||
| 484 | +Claude skips anything it can derive from the codebase, such as architecture, file paths, or debugging fixes. It also skips anything your CLAUDE.md files already say. | ||||
| 485 | + | ||||
| 486 | +Claude doesn't save something every session. It decides what's worth remembering based on whether the information would be useful in a future conversation. | ||||
| 487 | + | ||||
| 488 | +### Enable or disable auto memory | ||||
| 489 | + | ||||
| 490 | +Auto memory is on by default in local sessions. Outside [Claude Tag](https://claude.com/docs/claude-tag/overview) sessions, a session in a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled) runs with auto memory off by default. | ||||
| 491 | + | ||||
| 492 | +To toggle it, open `/memory` in a session and use the auto memory toggle, which saves `autoMemoryEnabled` to your user settings at `~/.claude/settings.json`. | ||||
| 493 | + | ||||
| 494 | +The toggle turns auto memory off but doesn't turn it back on in these sessions: | ||||
| 495 | + | ||||
| 496 | +* A [background session](https://code.claude.com/docs/en/agent-view.md) | ||||
| 497 | +* A session that another Claude Code session started, such as when Claude runs `claude` through its Bash tool | ||||
| 498 | + | ||||
| 499 | +While auto memory is off there, the toggle reads `off · can't be turned on here; use a session started outside Claude Code`. To turn auto memory back on, run `claude` directly in your terminal and use the `/memory` toggle in that session. | ||||
| 500 | + | ||||
| 501 | +To turn it off for a single project, set `autoMemoryEnabled` in that project's settings: | ||||
| 502 | + | ||||
| 503 | +```json theme={null} | ||||
| 504 | +{ | ||||
| 505 | + "autoMemoryEnabled": false | ||||
| 506 | +} | ||||
| 507 | +``` | ||||
| 508 | + | ||||
| 509 | +To disable auto memory via environment variable, set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`. | ||||
| 510 | + | ||||
| 511 | +### Storage location | ||||
| 512 | + | ||||
| 513 | +Each project gets its own memory directory at `~/.claude/projects/<project>/memory/`. The `<project>` path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead. | ||||
| 514 | + | ||||
| 515 | +If you set [`CLAUDE_CODE_PROJECT_DIR_NAME`](https://code.claude.com/docs/en/sessions#name-the-project-directory-yourself) beside `CLAUDE_CONFIG_DIR`, Claude Code uses that name as the `<project>` directory under `<config dir>/projects/` instead, whichever repository you launch it in, so projects launched with that config directory share one auto memory directory. Requires Claude Code v2.1.234 or later. | ||||
| 516 | + | ||||
| 517 | +To store auto memory in a different location, set `autoMemoryDirectory` in your `settings.json`. It is read from any [settings scope](https://code.claude.com/docs/en/settings.md#settings-precedence): user, project, local, policy, or `--settings`. | ||||
| 518 | + | ||||
| 519 | +```json theme={null} | ||||
| 520 | +{ | ||||
| 521 | + "autoMemoryDirectory": "~/my-custom-memory-dir" | ||||
| 522 | +} | ||||
| 523 | +``` | ||||
| 524 | + | ||||
| 525 | +The value must be an absolute path or start with `~/`. | ||||
| 526 | + | ||||
| 527 | +When you set it in a project's `.claude/settings.json` or `.claude/settings.local.json`, Claude Code honors it under the same [workspace trust rule as hooks in settings files](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder). While [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories) is on, Claude Code loads no auto memory from a directory that a [repository-supplied settings file](https://code.claude.com/docs/en/permissions.md#when-your-local-settings-file-needs-trust) chooses and saves none to it, wherever that directory sits. | ||||
| 528 | + | ||||
| 529 | +The directory contains a `MEMORY.md` index and one topic file per memory: | ||||
| 530 | + | ||||
| 531 | +```text theme={null} | ||||
| 532 | +~/.claude/projects/<project>/memory/ | ||||
| 533 | +├── MEMORY.md # Index, one line per memory, loaded into every session | ||||
| 534 | +├── user_role.md # One memory | ||||
| 535 | +├── feedback_testing.md # One memory | ||||
| 536 | +└── ... # Any other topic files Claude creates | ||||
| 537 | +``` | ||||
| 538 | + | ||||
| 539 | +`MEMORY.md` acts as an index of the memory directory. Claude reads and writes files in this directory throughout your session, using `MEMORY.md` to keep track of what's stored where. | ||||
| 540 | + | ||||
| 541 | +Auto memory is machine-local. All worktrees and subdirectories within the same git repository share one auto memory directory. Files are not shared across machines or cloud environments. | ||||
| 542 | + | ||||
| 543 | +Claude Code deletes old session transcripts after the [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) retention period, but excludes the memory files in the memory directory from that [retention sweep](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically). `MEMORY.md` and topic files stay until you or Claude edits or deletes them. | ||||
| 544 | + | ||||
| 545 | +### How it works | ||||
| 546 | + | ||||
| 547 | +The first 200 lines of `MEMORY.md`, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start. Claude keeps `MEMORY.md` concise by moving detailed notes into separate topic files. | ||||
| 548 | + | ||||
| 549 | +After Claude writes to `MEMORY.md`, Claude Code measures the file against the 200-line and 25KB read limits. If the file is near a limit, Claude Code reminds Claude to shorten it: keep one line per entry, move detail into topic files, and merge or drop stale entries. If the file is over a limit, the write still succeeds, but Claude Code returns an [error telling Claude to rewrite the index](https://code.claude.com/docs/en/errors.md#memory-index-is-over-its-read-limit), because everything past the limit is dropped on the next load. | ||||
| 550 | + | ||||
| 551 | +> [!NOTE] | ||||
| 552 | +> | ||||
| 553 | +> This limit applies only to `MEMORY.md`. Claude gets the whole of each CLAUDE.md file that loads at launch, as long as the file is 4 MiB or smaller. Claude Code skips a file over 4 MiB and loads none of it. Path-scoped rules and CLAUDE.md files in subdirectories have [a smaller per-file limit of their own](#claude-ignores-the-end-of-my-subdirectory-claude-md). | ||||
| 554 | + | ||||
| 555 | +Claude Code doesn't load topic files such as `user_role.md` or `feedback_testing.md` at startup. Claude reads them on demand using its standard file tools when it needs the information. | ||||
| 556 | + | ||||
| 557 | +The main conversation's auto memory isn't loaded into [subagents](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup); the exception is a [fork](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), which inherits the parent conversation and system prompt. A subagent's own auto memory, enabled with the subagent `memory` field, is a separate directory. | ||||
| 558 | + | ||||
| 559 | +Claude reads and writes memory files during your session. When you see messages like "Saved 2 memories" or "Recalled 2 memories" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`. | ||||
| 560 | + | ||||
| 561 | +When Claude writes a memory file that begins with YAML frontmatter, Claude Code records the write time in a `modified` frontmatter field as an ISO 8601 timestamp. The timestamp shows how current the fact is, both to you and to Claude when it reads the memory back. | ||||
| 562 | + | ||||
| 563 | +### Audit and edit your memory | ||||
| 564 | + | ||||
| 565 | +Auto memory files are plain markdown you can edit or delete at any time. Run [`/memory`](#view-and-edit-with-%2Fmemory) to browse and open memory files from within a session. | ||||
| 566 | + | ||||
| 567 | +## View and edit with `/memory` | ||||
| 568 | + | ||||
| 569 | +The `/memory` command lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes, including user and project CLAUDE.md entries for files that don't exist yet. It also lets you toggle auto memory on or off and provides an option to open the auto memory folder. Select any file to open it in your editor; selecting one that doesn't exist yet creates it first. To check which `CLAUDE.md` and rules files loaded at launch, run `/context`. | ||||
| 570 | + | ||||
| 571 | +GUI editors such as VS Code open the file in a separate window, and you can keep using the session while it's open. Terminal editors such as Vim take over the terminal until you exit. | ||||
| 572 | + | ||||
| 573 | +When you ask Claude to remember something, like "always use pnpm, not npm" or "remember that the API tests require a local Redis instance," Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via `/memory`. | ||||
| 574 | + | ||||
| 575 | +## Troubleshoot memory issues | ||||
| 576 | + | ||||
| 577 | +These are the most common issues with CLAUDE.md and auto memory, along with steps to debug them. | ||||
| 578 | + | ||||
| 579 | +### Claude isn't following my CLAUDE.md | ||||
| 580 | + | ||||
| 581 | +CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions. | ||||
| 582 | + | ||||
| 583 | +To debug: | ||||
| 584 | + | ||||
| 585 | +* Run `/context` and check the list under **Memory files** to verify the CLAUDE.md and CLAUDE.local.md files that should load at launch. If one is missing there, Claude can't see it. Use `/memory` to open and edit the files. | ||||
| 586 | +* If an `Instruction file not loaded` notice appears, see [what it means and what to do about it](https://code.claude.com/docs/en/errors.md#instruction-file-not-loaded). | ||||
| 587 | +* A `CLAUDE.md` in a subdirectory of your working directory doesn't appear under **Memory files**, because it loads on demand rather than at launch. When it loads, a `Loaded` line with its path appears in the terminal. To test a new one, create it from your shell rather than asking Claude to write it, then ask Claude to read a file in that subdirectory. | ||||
| 588 | +* Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claude-md-files)). | ||||
| 589 | +* Make instructions more specific. "Use 2-space indentation" works better than "format code nicely." | ||||
| 590 | +* Look for conflicting instructions across CLAUDE.md files. If two files give different guidance for the same behavior, Claude may pick one arbitrarily. | ||||
| 591 | +* Check whether your instruction competes with guidance Claude Code adds on its own. If your CLAUDE.md sets commit or pull request rules, turn off the built-in ones with [`includeGitInstructions`](https://code.claude.com/docs/en/settings-reference#includegitinstructions) and set the attribution text with [`attribution`](https://code.claude.com/docs/en/settings-reference#attribution). | ||||
| 592 | + | ||||
| 593 | +If the instruction is something that must run at a specific point, such as before every commit or after each file edit, write it as a [hook](https://code.claude.com/docs/en/hooks-guide.md) instead. Hooks execute as shell commands at fixed lifecycle events and apply regardless of what Claude decides to do. | ||||
| 594 | + | ||||
| 595 | +For instructions you want at the system prompt level, use [`--append-system-prompt`](https://code.claude.com/docs/en/cli-reference#system-prompt-flags). You pass it at launch, so it's better suited to scripts and automation than interactive use. For how it behaves when you resume a conversation, see [System prompt flags in resumed conversations](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags-in-resumed-conversations). | ||||
| 596 | + | ||||
| 597 | +> [!TIP] | ||||
| 598 | +> | ||||
| 599 | +> Use the [`InstructionsLoaded` hook](https://code.claude.com/docs/en/hooks#instructionsloaded) to log which `CLAUDE.md` and rules files are loaded, when they load, and why. This is useful for debugging path-specific rules or lazy-loaded files in subdirectories. | ||||
| 600 | + | ||||
| 601 | +### My AGENTS.md isn't loading | ||||
| 602 | + | ||||
| 603 | +If your repository has an `AGENTS.md` and Claude doesn't seem to know what it says, the usual cause is a `CLAUDE.md` somewhere on the project path. By default Claude reads `AGENTS.md` only when you have no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. Check these in order: | ||||
| 604 | + | ||||
| 605 | +1. Look for a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in your working directory or any directory above it, other than your `~/.claude/CLAUDE.md`. If you find one, Claude reads it instead of `AGENTS.md` unless you set **Project instructions** to `claude-md-and-agents-md`. | ||||
| 606 | +2. Run `claude --version` and confirm v2.1.277 or later. Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, [couldn't load `AGENTS.md`](#when-agents-md-support-is-unavailable) either, so on those versions update to v2.1.281 or later. | ||||
| 607 | +3. Type `/config` in your session to open the settings panel and confirm **Project instructions** isn't set to `claude-md` or `managed-only`. If you don't see the setting there at all, your session is one that [can't load `AGENTS.md`](#when-agents-md-support-is-unavailable). | ||||
| 608 | + | ||||
| 609 | +To check whether Claude read your `AGENTS.md`, run `/memory` and look for its path in the list. | ||||
| 610 | + | ||||
| 611 | +Before v2.1.280, `/memory` and `/context` didn't list an `AGENTS.md` that Claude read directly. On those versions, ask Claude what its project instructions say instead. | ||||
| 612 | + | ||||
| 613 | +If you want to keep the `CLAUDE.md` you found, or your session can't load `AGENTS.md`, [add a `CLAUDE.md` next to your `AGENTS.md` that imports it](#share-one-file-with-other-coding-tools). | ||||
| 614 | + | ||||
| 615 | +### I don't know what auto memory saved | ||||
| 616 | + | ||||
| 617 | +Run `/memory` and select the auto memory folder to browse what Claude has saved. Everything is plain markdown you can read, edit, or delete. | ||||
| 618 | + | ||||
| 619 | +### My CLAUDE.md is too large | ||||
| 620 | + | ||||
| 621 | +Files over 200 lines consume more context and may reduce adherence. Claude Code skips a file over 4 MiB. Use [path-scoped rules](#path-specific-rules) to load instructions only when Claude works with matching files, or trim content that isn't needed in every session. Splitting into [`@path` imports](#import-additional-files) helps organization but doesn't reduce context, since imported files load with the CLAUDE.md importing them. | ||||
| 622 | + | ||||
| 623 | +If one of your instruction files is over the recommended length, you see a warning at startup and when you run `/status`. You also see a warning when files that are each within that length add up past a combined limit at session start. Each CLAUDE.md, rules file, and `@path` import counts as a separate file. | ||||
| 624 | + | ||||
| 625 | +The [`/doctor`](https://code.claude.com/docs/en/commands#all-commands) checkup proposes trims for a checked-in CLAUDE.md: it cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews, and keeps pitfalls, rationale, and conventions that differ from tool defaults. | ||||
| 626 | + | ||||
| 627 | +> [!NOTE] | ||||
| 628 | +> | ||||
| 629 | +> Keep each path-scoped rules file within [its own per-file size limit](#claude-ignores-the-end-of-my-subdirectory-claude-md), because Claude receives only the start of a file that's over it. | ||||
| 630 | + | ||||
| 631 | +### Claude ignores the end of my subdirectory CLAUDE.md | ||||
| 632 | + | ||||
| 633 | +When a subdirectory `CLAUDE.md` or a rules file that loads on demand is over a per-file size limit, Claude receives only the start of it. That part ends with a note telling Claude to read the rest with the Read tool, and until Claude chooses to, the later instructions aren't in its context. | ||||
| 634 | + | ||||
| 635 | +Check whether your file is over the limit, and shrink it if it is: | ||||
| 636 | + | ||||
| 637 | +1. Confirm that the limit applies to your file. The limit applies to these files, which load on demand: | ||||
| 638 | + * `CLAUDE.md` and `CLAUDE.local.md` in a subdirectory of the directory where you started Claude Code, and the files they [import](#import-additional-files) with `@path` | ||||
| 639 | + * Rules files in a subdirectory's `.claude/rules/` | ||||
| 640 | + * [Path-scoped rules](#path-specific-rules) in your project's `.claude/rules/` or in `~/.claude/rules/` | ||||
| 641 | +2. Find the limit for your session's [context window](https://code.claude.com/docs/en/model-config.md#extended-context): | ||||
| 642 | + * **200K context window**: 40,000 characters | ||||
| 643 | + * **1M context window**: 200,000 characters on Claude Opus 4.6 and Claude Sonnet 4.6, and 150,000 characters on later models | ||||
| 644 | +3. In Bash or Zsh, run `wc -m path/to/CLAUDE.md` to print your file's character count. | ||||
| 645 | +4. Compare the count with your limit: | ||||
| 646 | + * **Over the limit**: trim the file, or move part of it into one or more rules files, which each count against the limit on their own | ||||
| 647 | + * **Under the limit**: look for another cause under [Claude isn't following my CLAUDE.md](#claude-isn’t-following-my-claude-md) | ||||
| 648 | + | ||||
| 649 | +Before v2.1.309, Claude Code didn't apply this limit to files that load on demand. | ||||
| 650 | + | ||||
| 651 | +### Instructions seem lost after `/compact` | ||||
| 652 | + | ||||
| 653 | +Project-root CLAUDE.md survives compaction: after `/compact`, Claude re-reads it from disk and re-injects it into the session. Nested CLAUDE.md files in subdirectories and rules with [`paths:` frontmatter](#path-specific-rules) load again on demand. | ||||
| 654 | + | ||||
| 655 | +If an instruction disappeared after compaction, it was given only in conversation, lives in a nested CLAUDE.md that hasn't reloaded yet, or is a path-scoped rule that hasn't matched a file since. Add conversation-only instructions to CLAUDE.md to make them persist. See [What survives compaction](https://code.claude.com/docs/en/context-window.md#what-survives-compaction) for the full breakdown. | ||||
| 656 | + | ||||
| 657 | +See [Write effective instructions](#write-effective-instructions) for guidance on size, structure, and specificity. | ||||
| 658 | + | ||||
| 659 | +## Related resources | ||||
| 660 | + | ||||
| 661 | +* [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md): diagnose why CLAUDE.md or settings aren't taking effect | ||||
| 662 | +* [Skills](https://code.claude.com/docs/en/skills.md): package repeatable workflows that load on demand | ||||
| 663 | +* [Settings](https://code.claude.com/docs/en/settings.md): configure Claude Code behavior with settings files | ||||
| 664 | +* [Subagent memory](https://code.claude.com/docs/en/sub-agents.md#enable-persistent-memory): let subagents maintain their own auto memory | ||||
added
docs/claude-code-docs/permissions.md
+824 −0
@@ -0,0 +1,824 @@ | |||||
| 1 | +> ## Documentation Index | ||||
| 2 | +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt | ||||
| 3 | +> Use this file to discover all available pages before exploring further. | ||||
| 4 | + | ||||
| 5 | +# Configure permissions | ||||
| 6 | + | ||||
| 7 | +> Control what Claude Code can access and do with fine-grained permission rules, modes, and managed policies. | ||||
| 8 | + | ||||
| 9 | +Claude Code supports fine-grained permissions so that you can specify exactly what the agent is allowed to do and what it can't. You can check permission settings into version control to share them with every developer in your organization, and each developer can customize their own. | ||||
| 10 | + | ||||
| 11 | +## Permission system | ||||
| 12 | + | ||||
| 13 | +Claude Code uses a tiered permission system to balance power and safety. The table shows, for each tool type, whether Manual mode asks before the action runs. The other [permission modes](#permission-modes) change which of these ask you; in auto mode a classifier reviews actions instead of you, and [how the classifier evaluates actions](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions) lists which ones it sees. | ||||
| 14 | + | ||||
| 15 | +| Tool type | Example | Approval required | "Yes, and don't ask again" behavior | | ||||
| 16 | +| :- | :- | :- | :- | | ||||
| 17 | +| Read-only | File reads, Grep | No, within the [working directory and additional directories](#working-directories) | N/A | | ||||
| 18 | +| Bash commands | Shell execution | Yes, except a built-in set of [read-only commands](#read-only-commands) | Permanently per repository and command | | ||||
| 19 | +| File modification | Edit/write files | Yes | Until session end | | ||||
| 20 | +| Web fetch | WebFetch | Yes, except a built-in set of [preapproved documentation domains](https://code.claude.com/docs/en/tools-reference.md#webfetch-tool-behavior) | Permanently per repository and domain | | ||||
| 21 | +| Web search | WebSearch | Yes | Permanently per repository | | ||||
| 22 | + | ||||
| 23 | +A permission prompt shows what Claude is about to do, followed by your options. This example is the prompt for a Bash command, from a session in Manual mode: | ||||
| 24 | + | ||||
| 25 | + | ||||
| 26 | + | ||||
| 27 | +The third option, **Yes, and switch to auto mode**, [doesn't appear on every prompt](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes). | ||||
| 28 | + | ||||
| 29 | +When you choose "Yes, and don't ask again" and the approval saves permanently, such as for a Bash command or a WebFetch domain, Claude Code saves the rule to `.claude/settings.local.json` at the root of the git repository, resolved through [worktrees](https://code.claude.com/docs/en/worktrees.md) to the main checkout. The rule applies to future sessions anywhere in that repository, including sessions started in subdirectories and in worktrees. A file-modification approval isn't saved to the file: as the table shows, it lasts until the session ends. In some cases, such as outside a git repository or on Windows, Claude Code doesn't use the repository root; [Where Claude Code looks for each file](https://code.claude.com/docs/en/settings.md#where-claude-code-looks-for-each-file) lists those cases and where it saves the rule instead. | ||||
| 30 | + | ||||
| 31 | +Sometimes a permission prompt offers only a one-time approval, with no "don't ask again" option and no option to allow the action for the rest of the session. Claude Code offers those options only when the prompt can show you everything they would allow, so a rule you save from a prompt covers only what its option named. When a prompt offers only the one-time approval, approve the action once, or add the rule yourself in [`/permissions`](#manage-permissions). To stop the prompts for a command that starts with an exec wrapper such as `watch`, or for a `find` command with an action such as `-delete`, see [Exec wrappers and `find` actions](#exec-wrappers-and-find-actions). | ||||
| 32 | + | ||||
| 33 | +### Add a comment when you answer a permission prompt | ||||
| 34 | + | ||||
| 35 | +You can attach a note to Claude when you approve or deny a single action. On most permission prompts, including Bash, PowerShell, file, and MCP tool prompts, move to **Yes** or **No** and press `Tab` to open a comment field on that option. WebFetch and browser prompts don't offer the field. The options that allow the action for the rest of the session or save a rule don't take one either. | ||||
| 36 | + | ||||
| 37 | +With the field open, type the comment and then press one of these keys: | ||||
| 38 | + | ||||
| 39 | +* `Enter`: submits your answer with the comment attached. If you leave the field empty, Claude Code submits the answer without a comment. | ||||
| 40 | +* `Tab`: closes the field without answering. Claude Code keeps the text you typed and still sends it if you answer with that option. | ||||
| 41 | +* `Shift+Tab`: on a file prompt, such as an Edit or Write prompt, closes the field the same as `Tab`. Before v2.1.235, pressing `Shift+Tab` inside the field instead selected the option that allows the action for the rest of the session, so Claude Code approved the action for the rest of the session and discarded the comment. | ||||
| 42 | + | ||||
| 43 | +Claude Code delivers the comment differently depending on how you answered: | ||||
| 44 | + | ||||
| 45 | +* **Yes**: Claude Code runs the action, then sends your comment to Claude after the result. | ||||
| 46 | +* **No**: Claude Code sends your comment to Claude as the reason for the denial, and Claude continues working. If you select **No** without a comment on a prompt from the main conversation, Claude Code stops the turn. | ||||
| 47 | + | ||||
| 48 | +## Manage permissions | ||||
| 49 | + | ||||
| 50 | +You can view and manage Claude Code's tool permissions with `/permissions`. The dialog lists all permission rules and the `settings.json` file each rule comes from. You can open the dialog while Claude is working: when you add or remove a rule, Claude Code applies the change starting with Claude's next tool call in the same turn. Before v2.1.234, Claude Code queued the command until the turn finished. | ||||
| 51 | + | ||||
| 52 | +* **Allow** rules let Claude Code use the specified tool without manual approval. | ||||
| 53 | +* **Ask** rules prompt for confirmation whenever Claude Code tries to use the specified tool. | ||||
| 54 | +* **Deny** rules prevent Claude Code from using the specified tool. | ||||
| 55 | + | ||||
| 56 | +Rules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity doesn't change the order. | ||||
| 57 | + | ||||
| 58 | +A broad deny rule like `Bash(aws *)` blocks every matching call, including calls that also match a narrower allow rule like `Bash(aws s3 ls)`. An allow rule can't carve an exception out of a deny rule. The same precedence applies between ask and allow: a matching ask rule prompts even when a more specific allow rule also matches the same call. | ||||
| 59 | + | ||||
| 60 | +Deny rules behave differently depending on whether they name a tool or scope a pattern within one. A bare tool name like `Bash` removes the tool from Claude's context entirely, so Claude never sees it. If you add such a rule mid-session, Claude can't call the tool from its next tool call on; [Denying an entire tool](https://code.claude.com/docs/en/prompt-caching.md#denying-an-entire-tool) covers what happens to a definition Claude has already seen. A scoped rule like `Bash(rm *)` leaves the tool available and blocks matching calls when Claude attempts them. | ||||
| 61 | + | ||||
| 62 | +Bare-name removal applies to every tool except [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior): a deny rule can't remove it while any other tool remains, and an ask rule never prompts for it. | ||||
| 63 | + | ||||
| 64 | +> [!NOTE] | ||||
| 65 | +> | ||||
| 66 | +> Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or `CLAUDE.md` shape what Claude tries to do, but they don't change what Claude Code allows. To grant or revoke access, use `/permissions`, the rules described here, a [permission mode](https://code.claude.com/docs/en/permission-modes.md), or a [PreToolUse hook](#extend-permissions-with-hooks). | ||||
| 67 | + | ||||
| 68 | +When [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) is available to your session, the dialog also includes the [auto mode classifier rules](https://code.claude.com/docs/en/auto-mode-config.md#edit-rules-from-permissions). Select the **Auto mode** tab to view them. | ||||
| 69 | + | ||||
| 70 | +## Permission modes | ||||
| 71 | + | ||||
| 72 | +Claude Code supports several permission modes that control how it approves tool calls. See [Permission modes](https://code.claude.com/docs/en/permission-modes.md) for when to use each one. To change the mode sessions start in, set `defaultMode` in your [settings files](https://code.claude.com/docs/en/settings.md#where-settings-live). [Which mode a session starts in](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) covers the built-in default for each plan and what the VS Code extension reads. | ||||
| 73 | + | ||||
| 74 | +| Mode | Description | | ||||
| 75 | +| :- | :- | | ||||
| 76 | +| `default` | Prompts for permission on first use of each tool. Labeled Manual in the CLI, the VS Code and JetBrains extensions, and the desktop app, and Claude Code accepts `manual` as an alias | | ||||
| 77 | +| `acceptEdits` | Automatically accepts file edits and common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp` for paths in the working directory or `additionalDirectories` | | ||||
| 78 | +| `plan` | Claude reads files and runs read-only shell commands to explore but doesn't edit your source files; with [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) available, classifier-approved commands also run. Labeled Plan in the CLI and the VS Code extension | | ||||
| 79 | +| `auto` | Runs without routine prompts; before actions such as shell commands and network requests run, a background [classifier](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) checks that they align with your request | | ||||
| 80 | +| `dontAsk` | Auto-denies every call that would otherwise prompt, though a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you installed can still approve some of those calls. File reads in your working directories and other actions that need no approval still run, as do tools pre-approved via `/permissions` or `permissions.allow` rules. `AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool), [reads from network paths](#network-paths), and connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code are denied even if you've allowed them | | ||||
| 81 | +| `bypassPermissions` | Skips permission prompts, except for the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) | | ||||
| 82 | + | ||||
| 83 | +> [!WARNING] | ||||
| 84 | +> | ||||
| 85 | +> In `bypassPermissions` mode, Claude Code skips permission prompts, including for writes to [protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths) such as `.git` and `.claude`. The [cross-session messaging safeguards](https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) still apply. Only use this mode in isolated environments like containers or VMs where Claude Code can't cause damage. | ||||
| 86 | + | ||||
| 87 | +To prevent `bypassPermissions` or `auto` mode from being used, set `permissions.disableBypassPermissionsMode` or `permissions.disableAutoMode` to `"disable"` in any [settings file](https://code.claude.com/docs/en/settings.md#where-settings-live). These are most useful in [managed settings](#managed-settings) where they can't be overridden. | ||||
| 88 | + | ||||
| 89 | +## Permission rule syntax | ||||
| 90 | + | ||||
| 91 | +Permission rules follow the format `Tool` or `Tool(specifier)`. Parentheses inside the specifier are literal, so a command or path that contains them needs no escaping. | ||||
| 92 | + | ||||
| 93 | +### Match all uses of a tool | ||||
| 94 | + | ||||
| 95 | +To match all uses of a tool, use only the tool name without parentheses: | ||||
| 96 | + | ||||
| 97 | +| Rule | Effect | | ||||
| 98 | +| :- | :- | | ||||
| 99 | +| `Bash` | Matches all Bash commands | | ||||
| 100 | +| `WebFetch` | Matches all web fetch requests | | ||||
| 101 | +| `Read` | Matches all file reads | | ||||
| 102 | + | ||||
| 103 | +`Bash(*)` is equivalent to `Bash` and matches all Bash commands. As a deny rule, both forms remove the tool from Claude's context. | ||||
| 104 | + | ||||
| 105 | +The label shown for a tool in the transcript and permission dialog can differ from its canonical name. For example, the tool labeled `Stop Task` in the transcript has the canonical name `TaskStop`. Permission rules and [hook matchers](https://code.claude.com/docs/en/hooks.md) don't match the label, so a rule written as `Stop Task` doesn't match. For deny and ask rules, a [startup warning](https://code.claude.com/docs/en/errors.md#matches-no-tool) says so. Use the canonical names listed in the [tools reference](https://code.claude.com/docs/en/tools-reference.md). | ||||
| 106 | + | ||||
| 107 | +### Use specifiers for fine-grained control | ||||
| 108 | + | ||||
| 109 | +Add a specifier in parentheses to match specific tool uses: | ||||
| 110 | + | ||||
| 111 | +| Rule | Effect | | ||||
| 112 | +| :- | :- | | ||||
| 113 | +| `Bash(npm run build)` | Matches the exact command `npm run build` | | ||||
| 114 | +| `Read(./.env)` | Matches reading the `.env` file in the current directory | | ||||
| 115 | +| `WebFetch(domain:example.com)` | Matches fetch requests to example.com | | ||||
| 116 | + | ||||
| 117 | +### Match by input parameter | ||||
| 118 | + | ||||
| 119 | +Deny and ask rules can match a top-level input parameter on any built-in tool with `Tool(param:value)`. | ||||
| 120 | + | ||||
| 121 | +To match a parameter on an MCP tool, pass a deny rule with [`--disallowedTools`](https://code.claude.com/docs/en/cli-reference#cli-flags). When Claude Code loads a settings file, it skips any `mcp__` rule that has parentheses. Claude Code lists the skipped rule in the invalid-settings dialog when an interactive session starts, and in [`claude doctor`](https://code.claude.com/docs/en/debug-your-config#check-resolved-settings) output. | ||||
| 122 | + | ||||
| 123 | +A parameter rule matches when Claude calls the tool with that parameter set to that exact value. An allow rule for one parameter value wouldn't establish that the call is safe overall, so allow rules continue to use each tool's own specifier syntax. This works for any scalar parameter the tool accepts: | ||||
| 124 | + | ||||
| 125 | +| Rule | Matches | | ||||
| 126 | +| :- | :- | | ||||
| 127 | +| `Agent(model:opus)` | Agent calls that request the Opus model tier | | ||||
| 128 | +| `Agent(isolation:worktree)` | Agent calls that request a git worktree | | ||||
| 129 | +| `Bash(run_in_background:true)` | Bash calls that run in the background | | ||||
| 130 | + | ||||
| 131 | +Parameter matching follows these rules: | ||||
| 132 | + | ||||
| 133 | +* The parameter name must be a direct field of the tool's input, such as `model` on the Agent tool. Fields nested inside an object or array are not matchable | ||||
| 134 | +* Each rule names one parameter. To gate on both `model` and `isolation`, write two rules, `Agent(model:opus)` and `Agent(isolation:worktree)`, rather than combining them in one rule | ||||
| 135 | +* The value supports `*` as a wildcard that matches any sequence of characters, so `Agent(isolation:*)` matches any explicit isolation value. Without `*` the match is exact | ||||
| 136 | +* A parameter the model omits is never matched, so `Agent(model:*)` doesn't match a call that leaves `model` unset | ||||
| 137 | +* The value is compared against the literal input Claude sends, before any normalization. `Agent(model:opus)` matches the alias `opus` but not a full model ID | ||||
| 138 | +* A `Skill(skill:<name>)` deny rule instead [matches the skill under any of its names](https://code.claude.com/docs/en/skills.md#restrict-claude’s-skill-access), such as its alias or display name | ||||
| 139 | +* Run with [`--verbose`](https://code.claude.com/docs/en/cli-reference) to see the exact parameter names and values in each tool call | ||||
| 140 | +* Whitespace around the colon is ignored | ||||
| 141 | + | ||||
| 142 | +You can't match a tool's primary content field this way: `command` for Bash and PowerShell, `file_path` for Read, Edit, and Write, `path` for Grep and Glob, `notebook_path` for NotebookEdit, and `url` for WebFetch. A rule like `Bash(command:rm *)` would be bypassable by a compound command, so Claude Code ignores it and emits a startup warning. Use `Bash(rm *)`, `Read(./path)`, or `WebFetch(domain:host)` instead. | ||||
| 143 | + | ||||
| 144 | +### Wildcard patterns | ||||
| 145 | + | ||||
| 146 | +A `*` in a Bash rule matches any text, including spaces, so one rule covers a family of commands. A rule with no `*` matches one exact command. | ||||
| 147 | + | ||||
| 148 | +> [!WARNING] | ||||
| 149 | +> | ||||
| 150 | +> Put the `*` after the subcommand. In `git log --oneline main`, `git` is the program and `log` is the subcommand, the word that determines what the program does. Claude Code matches everything before the first `*` as written, so those words are what limit the rule: `Bash(git log *)` allows only `git log` commands, and `Bash(git *)` allows every git command. Claude Code [warns at startup](https://code.claude.com/docs/en/errors.md#has-a-wildcard-before-the-rest-of-the-command) about an allow rule with a `*` before the subcommand, such as `Bash(git * main)`. | ||||
| 151 | + | ||||
| 152 | +Write the command you want Claude to run without asking, and replace the parts that vary with `*`. With this configuration, Claude Code runs npm scripts and git commits without asking and refuses commands that begin with `git push`. A push written another way, such as `git -C . push`, isn't matched; see [what a Bash rule doesn't match](#bash-rule-limits). | ||||
| 153 | + | ||||
| 154 | +```json theme={null} | ||||
| 155 | +{ | ||||
| 156 | + "permissions": { | ||||
| 157 | + "allow": [ | ||||
| 158 | + "Bash(npm run *)", | ||||
| 159 | + "Bash(git commit *)" | ||||
| 160 | + ], | ||||
| 161 | + "deny": [ | ||||
| 162 | + "Bash(git push *)" | ||||
| 163 | + ] | ||||
| 164 | + } | ||||
| 165 | +} | ||||
| 166 | +``` | ||||
| 167 | + | ||||
| 168 | +A `*` can go anywhere in the rule: at the start, in the middle, or at the end. Each row shows a rule, commands it matches, and nearby commands it doesn't match: | ||||
| 169 | + | ||||
| 170 | +| You write | Matches | Doesn't match | | ||||
| 171 | +| :- | :- | :- | | ||||
| 172 | +| `Bash(npm run build)` | `npm run build` | `npm run build --watch` | | ||||
| 173 | +| `Bash(npm run *)` | `npm run build`, `npm run test --watch`, `npm run` | `npm install` | | ||||
| 174 | +| `Bash(git log * main)` | `git log --oneline main`, `git log -5 main`, `git log --output=<file> main` | `git log main`, `git push origin main` | | ||||
| 175 | +| `Bash(git * main)` | `git merge main`, `git push origin main`, `git -c core.fsmonitor=<script> diff main` | `git log` | | ||||
| 176 | +| `Bash(* --version)` | `node --version`, `bash -c 'echo hi' --version` | `node -v` | | ||||
| 177 | +| `Bash(ls *)` | `ls -la`, `ls` | `lsof` | | ||||
| 178 | +| `Bash(ls*)` | `ls -la`, `lsof` | | | ||||
| 179 | +| `Bash(* --help *)` | `npm --help x` | `npm --help` | | ||||
| 180 | + | ||||
| 181 | +Three matching rules produce those rows: | ||||
| 182 | + | ||||
| 183 | +* **The `*` stands in for whatever text is in its place.** In `Bash(git * main)`, it stands in for the subcommand, so Claude Code matches every git subcommand and every option before it. That includes `-c`, which makes git run a program you name. In `Bash(* --version)`, the `*` stands in for the program, so any program matches. | ||||
| 184 | +* **A `*` at the end, with a space before it, also matches the bare command.** `Bash(ls *)` matches `ls`, and `Bash(git log *)` matches `git log`. That holds only when the trailing `*` is the rule's only wildcard: `Bash(* --help *)` matches `npm --help x` but not `npm --help`. | ||||
| 185 | +* **The space before a trailing `*` is part of the rule.** `Bash(ls *)` requires a space after `ls`, so `lsof` doesn't match. `Bash(ls*)` has no space, so it matches `lsof` too. | ||||
| 186 | + | ||||
| 187 | +The `:*` suffix is an equivalent way to write a trailing wildcard, so `Bash(ls:*)` matches the same commands as `Bash(ls *)`. | ||||
| 188 | + | ||||
| 189 | +The permission dialog writes the space-separated form when you select "Yes, and don't ask again" for a command prefix. The `:*` form is only recognized at the end of a pattern. In a pattern like `Bash(git:* push)`, the colon is treated as a literal character and won't match git commands. | ||||
| 190 | + | ||||
| 191 | +### Tool name wildcards | ||||
| 192 | + | ||||
| 193 | +Deny and ask rules also accept glob patterns in the tool-name position. The pattern must match the full tool name: `"*"` matches every tool, and `"mcp__*"` matches every MCP tool across all servers. A tool matched by a bare-name glob deny rule is removed from Claude's context, the same as a bare tool name, including the [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) exception: a glob deny can't remove it while any other tool remains, and a glob ask never prompts for it. This configuration denies every MCP tool: | ||||
| 194 | + | ||||
| 195 | +```json theme={null} | ||||
| 196 | +{ | ||||
| 197 | + "permissions": { | ||||
| 198 | + "deny": [ | ||||
| 199 | + "mcp__*" | ||||
| 200 | + ] | ||||
| 201 | + } | ||||
| 202 | +} | ||||
| 203 | +``` | ||||
| 204 | + | ||||
| 205 | +Allow rules accept tool-name globs only after a literal `mcp__<server>__` prefix. The server segment must be glob-free so the rule names a specific server you configured. `mcp__puppeteer__*` matches every tool from the `puppeteer` server, and `mcp__github__get_*` matches its `get_` tools. An unanchored allow glob such as `"*"`, `"B*"`, or `"mcp__*"` is skipped and doesn't auto-approve anything. | ||||
| 206 | + | ||||
| 207 | +A deny or ask rule whose tool name matches no known tool produces a [startup warning](https://code.claude.com/docs/en/errors.md#matches-no-tool) to catch typos. Tool names containing `_` or `*` are exempt from the check, and so are the names of tools Claude Code has removed, such as `TaskOutput`. | ||||
| 208 | + | ||||
| 209 | +## Tool-specific permission rules | ||||
| 210 | + | ||||
| 211 | +### Bash | ||||
| 212 | + | ||||
| 213 | +Bash rules match the whole command text, with `*` standing in for any text. [Wildcard patterns](#wildcard-patterns) shows which commands each rule shape matches and where to put the `*`. The rest of this section covers how Claude Code matches compound commands and wrappers, which wrappers and `find` actions a prefix rule can't approve, what a rule doesn't match, read-only commands, and redirections. | ||||
| 214 | + | ||||
| 215 | +#### Compound commands | ||||
| 216 | + | ||||
| 217 | +> [!TIP] | ||||
| 218 | +> | ||||
| 219 | +> Claude Code is aware of shell operators, so a rule like `Bash(safe-cmd *)` won't give it permission to run the command `safe-cmd && other-cmd`. The recognized command separators are `&&`, `||`, `;`, `|`, `|&`, `&`, and newlines. Every subcommand must be allowed for a compound command to run without a prompt, for example because the subcommand matches an allow rule or is a [read-only command](#read-only-commands). | ||||
| 220 | + | ||||
| 221 | +Deny and ask rules apply when any subcommand matches them, including a command nested inside a subshell, a command substitution, or a control-flow body such as a `for` loop. An ask rule like `Bash(git clean *)` still prompts you for `cd /tmp && git clean -f` or `echo "$(git clean -f)"`, even in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode). | ||||
| 222 | + | ||||
| 223 | +When `&&` or `||` has nothing after it, such as in `npm test &&`, Claude Code treats the command as unparseable and doesn't split it into subcommands for allow-rule matching, so a rule such as `Bash(npm *)` doesn't approve it. | ||||
| 224 | + | ||||
| 225 | +When you approve a compound command with "Yes, and don't ask again", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving `git status && npm test` saves a rule for `npm test`, so future `npm test` invocations are recognized regardless of what precedes the `&&`. Subcommands like `cd` into a directory outside your working directories generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command. | ||||
| 226 | + | ||||
| 227 | +#### Wrappers | ||||
| 228 | + | ||||
| 229 | +Before matching Bash rules, Claude Code strips a fixed set of wrappers, so a rule like `Bash(npm test *)` also matches `timeout 30 npm test`. The stripped wrappers are `timeout`, `time`, `nice`, `nohup`, and `stdbuf`, plus the shell builtins `command` and `builtin`, and zsh's `noglob`. Each runs its argument as the actual command. Two related forms aren't stripped: the query form `command -v`, which looks up a command rather than running one, and zsh's `nocorrect`. | ||||
| 230 | + | ||||
| 231 | +Claude Code also strips a leading assignment of certain known-safe environment variables, so `Bash(npm test *)` matches `NODE_ENV=test npm test`. An allow rule won't match past an assignment of any other variable. A deny or ask rule matches past any leading assignment, so `Bash(rm *)` in deny still matches `FOO=bar rm -rf tmp/`. | ||||
| 232 | + | ||||
| 233 | +Bare `xargs` is also stripped, so `Bash(grep *)` matches `xargs grep pattern`. Stripping applies only when `xargs` has no flags: an invocation like `xargs -n1 grep pattern` is matched as an `xargs` command, so rules written for the inner command do not cover it. | ||||
| 234 | + | ||||
| 235 | +This wrapper list is built in and is not configurable. Development environment runners such as `direnv exec`, `devbox run`, `mise exec`, `npx`, and `docker exec` are not in the list. Because these tools execute their arguments as a command, a rule like `Bash(devbox run *)` matches whatever comes after `run`, including `devbox run rm -rf .`. To approve work inside an environment runner, write a specific rule that includes both the runner and the inner command, such as `Bash(devbox run npm test)`. Add one rule per inner command you want to allow. | ||||
| 236 | + | ||||
| 237 | +#### Exec wrappers and `find` actions | ||||
| 238 | + | ||||
| 239 | +A prefix rule like `Bash(watch *)` or `Bash(find *)` can't auto-approve the following commands, so in Manual mode they prompt: | ||||
| 240 | + | ||||
| 241 | +* **Exec wrappers**: such as `watch`, `setsid`, `ionice`, and `flock` | ||||
| 242 | +* **`find`**: with an action that runs commands, deletes files, or writes files, such as `-exec`, `-delete`, `-rm`, or `-fprint`, or with `-files0-from`, which takes the paths to search from a file | ||||
| 243 | + | ||||
| 244 | +To approve a specific invocation that has no `*` in it, write an exact-match rule for the full command string, such as `Bash(find build -type f -delete)`. | ||||
| 245 | + | ||||
| 246 | +When the command has a `*`, as in `find . -name '*.tmp' -delete`, Claude Code reads the rule as a [wildcard pattern](#wildcard-patterns), not an exact match, so the command still prompts. Approve it each time it prompts, or use a [PreToolUse hook](https://code.claude.com/docs/en/hooks.md#pretooluse-decision-control) that returns `"allow"` for it. | ||||
| 247 | + | ||||
| 248 | +#### What a Bash rule doesn't match | ||||
| 249 | + | ||||
| 250 | +A Bash rule matches the command text Claude writes, after Claude Code splits [compound commands](#compound-commands) and strips [wrappers](#process-wrappers). It doesn't match the same program invoked in a different form, so a deny or ask rule covers the invocation Claude usually produces and isn't a security boundary around the program. These rules in `deny` or `ask` stop the first form and not the others: | ||||
| 251 | + | ||||
| 252 | +| Rule | Stops | Doesn't stop | | ||||
| 253 | +| :- | :- | :- | | ||||
| 254 | +| `Bash(curl *)` | `curl https://example.com` | `/usr/bin/curl https://example.com`, `sh -c 'curl https://example.com'` | | ||||
| 255 | +| `Bash(rm *)` | `rm -rf build/` | `/bin/rm -rf build/`, `bash -c 'rm -rf build/'` | | ||||
| 256 | +| `Bash(git push *)` | `git push origin main` | `git -C . push origin main`, `git -c push.default=current push origin main`, `git 'push' origin main` | | ||||
| 257 | + | ||||
| 258 | +Your other rules and the permission mode decide the commands in the last column. | ||||
| 259 | + | ||||
| 260 | +For filesystem and network enforcement that doesn't depend on the command text, use [sandboxing](https://code.claude.com/docs/en/sandboxing.md). To inspect the full command text with your own logic before it runs, use a [PreToolUse hook](#extend-permissions-with-hooks). | ||||
| 261 | + | ||||
| 262 | +#### Read-only commands | ||||
| 263 | + | ||||
| 264 | +Claude Code recognizes a built-in set of Bash commands as read-only and runs them without a permission prompt in every mode, except as [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories) changes for paths outside your working directories. The set includes `ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`, `wc`, `which`, `diff`, `stat`, `du`, `cd`, and read-only forms of `git`. The set is not configurable; to require a prompt for one of these commands, add an `ask` or `deny` rule for it. In auto mode, these commands can also wait for the classifier's review; see [how the classifier evaluates actions](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions). | ||||
| 265 | + | ||||
| 266 | +A redirect such as `ls > out.txt` adds a check on the target. See [Redirections](#redirections). | ||||
| 267 | + | ||||
| 268 | +Unquoted glob patterns are permitted for commands whose every flag is read-only, so `ls *.ts` and `wc -l src/*.py` run without a prompt. | ||||
| 269 | + | ||||
| 270 | +In Manual mode, commands from this set still prompt in these cases: | ||||
| 271 | + | ||||
| 272 | +* **Unquoted globs for commands with write-capable flags**: commands with write-capable or exec-capable flags, such as `find`, `sort`, `sed`, and `git`, prompt when an unquoted glob is present, because the glob could expand to a flag like `-delete`. | ||||
| 273 | +* **`docker` pointed at another daemon**: read-only forms of `docker` prompt when the command carries a flag that selects a different daemon, such as `-H`, `--context`, or Podman's `--url` and `--connection`. | ||||
| 274 | +* **`file` with path-opening flags**: `file` prompts when it passes `-m`/`--magic-file` or `-f`/`--files-from`, because those flags make `file` open the paths named in the flag's value. | ||||
| 275 | +* **`ps` that could print environment variables**: `ps` prompts when one of its arguments could act as the `e` option, such as in `ps auxe` or `ps aux -e`, because that option prints process environment variables. `ps aux` and `ps -ef` run without a prompt. The check on dashed forms such as `ps aux -e` requires Claude Code v2.1.290 or later. | ||||
| 276 | +* **Network paths on Windows**: a command whose arguments include a network (UNC) path, such as `\\server\share\file`, prompts because accessing a network path can send your Windows credentials to the host it names. The same check applies to [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) commands. | ||||
| 277 | +* **Writes to special shell variables**: a command that sets, unsets, or loops over certain special shell variables, such as `PATH` or `IFS`, prompts even when the rest of the command is read-only. | ||||
| 278 | +* **Commands the analysis can't parse**: when Claude Code can't fully parse a command, it asks for approval instead of treating the command as read-only. Commands longer than 10,000 characters always prompt because they exceed what the analysis parses. | ||||
| 279 | + | ||||
| 280 | +A `cd` into a path inside your working directory or an [additional directory](#working-directories) is also read-only, and a compound command like `cd packages/api && ls` runs without a prompt when each part qualifies on its own. These combinations prompt even when each part is read-only: | ||||
| 281 | + | ||||
| 282 | +* **`cd` with `git`**: prompts when the `cd` changes into a different directory, since running `git` in a new directory can execute that directory's hooks. A `cd` whose target resolves to the current working directory is a no-op and doesn't trigger the prompt. | ||||
| 283 | +* **`cd` with a redirect**: prompts when Claude Code can't determine which directory the redirect target resolves against after the `cd` runs. A command whose only redirect target is `/dev/null`, such as `cd app; grep -r pattern . 2>/dev/null`, doesn't prompt, because `/dev/null` doesn't depend on the working directory. | ||||
| 284 | + | ||||
| 285 | +> [!WARNING] | ||||
| 286 | +> | ||||
| 287 | +> Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/ *)` intends to restrict curl to GitHub URLs, but won't match variations like: | ||||
| 288 | +> | ||||
| 289 | +> * Options before URL: `curl -X GET http://github.com/...` | ||||
| 290 | +> * Different protocol: `curl https://github.com/...` | ||||
| 291 | +> * Redirects: `curl -L http://short.example.com/xyz`, which redirects to GitHub | ||||
| 292 | +> * Variables: `URL=http://github.com && curl $URL` | ||||
| 293 | +> | ||||
| 294 | +> For more reliable URL filtering, consider: | ||||
| 295 | +> | ||||
| 296 | +> * **Restrict Bash network tools**: use deny rules to stop `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains. A deny rule doesn't match the same program by path or inside `sh -c`, so pair it with the [sandbox network allowlist](https://code.claude.com/docs/en/sandboxing.md#network-isolation) when the restriction must hold; see [what a Bash rule doesn't match](#bash-rule-limits) | ||||
| 297 | +> * **Use PreToolUse hooks**: implement a hook that validates URLs in Bash commands and blocks disallowed domains | ||||
| 298 | +> * **Add CLAUDE.md guidance**: describe your allowed curl patterns in `CLAUDE.md`. This shapes what Claude tries but doesn't enforce a boundary, so pair it with one of the options above | ||||
| 299 | +> | ||||
| 300 | +> Note that using WebFetch alone doesn't prevent network access. If Bash is allowed, Claude can still use `curl`, `wget`, or other tools to reach any URL. | ||||
| 301 | + | ||||
| 302 | +#### Redirections | ||||
| 303 | + | ||||
| 304 | +When a command redirects output or input, Claude Code checks the redirect target against your file rules as if Claude wrote or read that file directly: | ||||
| 305 | + | ||||
| 306 | +* **Output redirects**: for `> file`, `>> file`, or `2> file`, the check covers your `Edit` allow and deny rules, [protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths), and the [working directories](#working-directories). A rule such as `Bash(git commit *)` allows the command, not the target. A target that starts with `~` or contains a glob character needs your approval. | ||||
| 307 | +* **Input redirects**: for `< file`, the check covers your `Read` allow and deny rules and the working directories. A target outside the working directories needs your approval unless an allow rule covers it. A target that contains a glob pattern, or a relative path that follows a `cd` in the same command, needs your approval even when an allow rule covers it. Claude Code checks input targets in v2.1.257 and later. | ||||
| 308 | + | ||||
| 309 | +Targets with no file behind them aren't checked: `/dev/null`, file-descriptor forms such as `2>&1` and `<&3`, and here-docs and here-strings. | ||||
| 310 | + | ||||
| 311 | +Claude Code also checks the files a `tee` command writes, including in a pipeline such as `make | tee build.log`. The check covers your `Edit` allow and deny rules, [protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths), and the [working directories](#working-directories). An allow rule such as `Bash(tee *)` doesn't cover a destination outside the working directories. Claude Code checks `tee` targets in v2.1.269 and later. | ||||
| 312 | + | ||||
| 313 | +### PowerShell | ||||
| 314 | + | ||||
| 315 | +PowerShell permission rules use the same shape as [Bash rules](#wildcard-patterns), and a bare `PowerShell` or `PowerShell(*)` matches every command. This configuration allows `Get-ChildItem` and `git commit` commands while blocking `Remove-Item`: | ||||
| 316 | + | ||||
| 317 | +```json theme={null} | ||||
| 318 | +{ | ||||
| 319 | + "permissions": { | ||||
| 320 | + "allow": [ | ||||
| 321 | + "PowerShell(Get-ChildItem *)", | ||||
| 322 | + "PowerShell(git commit *)" | ||||
| 323 | + ], | ||||
| 324 | + "deny": [ | ||||
| 325 | + "PowerShell(Remove-Item *)" | ||||
| 326 | + ] | ||||
| 327 | + } | ||||
| 328 | +} | ||||
| 329 | +``` | ||||
| 330 | + | ||||
| 331 | +Common aliases are canonicalized before matching. A rule written for the cmdlet name also matches those aliases, so `PowerShell(Get-ChildItem *)` matches `gci`, `ls`, and `dir` as well. Matching is case-insensitive. | ||||
| 332 | + | ||||
| 333 | +Claude Code parses the PowerShell AST and checks each command in a compound command independently. Pipeline operators `|`, statement separators `;`, and on PowerShell 7+ the chain operators `&&` and `||` split a compound command into subcommands. Every subcommand must be allowed for the compound command to run without a prompt, for example by matching an allow rule. | ||||
| 334 | + | ||||
| 335 | +### Read and Edit | ||||
| 336 | + | ||||
| 337 | +To block Claude's file tools from reading a file or directory, add a `Read` deny rule for its path, such as `Read(./.env)` or `Read(./secrets/**)`; [Exclude sensitive files](https://code.claude.com/docs/en/settings-reference.md#exclude-sensitive-files) has a paste-ready example. If your project has a `.claudeignore` file, it has no effect, so move its entries into `Read` deny rules. | ||||
| 338 | + | ||||
| 339 | +#### What `Read` and `Edit` rules cover | ||||
| 340 | + | ||||
| 341 | +`Edit` rules apply to all built-in tools that edit files. Claude makes a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep and Glob, to `@file` mentions in your prompts, and to the selection and open-file context that a connected [IDE](https://code.claude.com/docs/en/vs-code.md#the-built-in-ide-mcp-server) shares with Claude. | ||||
| 342 | + | ||||
| 343 | +A `Read(path)` deny rule also applies to image paths you paste into a prompt and directories you @-mention: | ||||
| 344 | + | ||||
| 345 | +* **Image path**: when you paste an image's path or drag an image file into your prompt in the terminal and the rule matches that path, Claude Code doesn't attach the image. If the paste holds no other image, the path stays in your prompt as text. | ||||
| 346 | +* **Directory**: the [listing Claude receives](https://code.claude.com/docs/en/common-workflows.md#reference-files-and-directories) leaves out the file and directory names the rule matches. | ||||
| 347 | + | ||||
| 348 | +Claude Code checks pasted image paths and directory listings in v2.1.290 and later. | ||||
| 349 | + | ||||
| 350 | +A `Read` deny rule also blocks the [Edit and Write tools](https://code.claude.com/docs/en/errors.md#file-is-covered-by-a-read-deny-rule) on the same path, including creating a new file there. NotebookEdit isn't covered, so add an `Edit` deny rule for paths no tool may change. For the Write tool, the check requires Claude Code v2.1.228 or later. | ||||
| 351 | + | ||||
| 352 | +> [!WARNING] | ||||
| 353 | +> | ||||
| 354 | +> Read and Edit deny rules apply to Claude's built-in file tools, to file commands Claude Code recognizes in Bash, such as `cat`, `head`, `tail`, `sed`, and `tee`, and to the targets of Bash [redirections](#redirections) such as `> file` and `< file`. They don't apply to a command that reads files without naming them, such as `grep -r pattern .` run from the directory that holds the file, or to arbitrary subprocesses that read or write files indirectly, like a Python or Node script that opens files itself. For OS-level enforcement that blocks all processes from accessing a path, [enable the sandbox](https://code.claude.com/docs/en/sandboxing.md). | ||||
| 355 | + | ||||
| 356 | +#### `Write(path)`, `NotebookEdit(path)`, and `Glob(path)` rules never match | ||||
| 357 | + | ||||
| 358 | +Claude Code checks file permissions against `Edit(path)` and `Read(path)` rules only. If you write a path rule for `Write`, `NotebookEdit`, `Glob`, or legacy `MultiEdit`, Claude Code accepts the rule but never matches a read or edit against it. | ||||
| 359 | + | ||||
| 360 | +Use `Edit(docs/**)` in place of `Write(docs/**)`, `NotebookEdit(docs/**)`, or `MultiEdit(docs/**)`, and `Read(docs/**)` in place of `Glob(docs/**)`. To match every use of the Write, NotebookEdit, or Glob tool regardless of path, write only the tool name. | ||||
| 361 | + | ||||
| 362 | +#### How path patterns match | ||||
| 363 | + | ||||
| 364 | +Read and Edit rules both use [gitignore](https://git-scm.com/docs/gitignore) pattern syntax with four distinct pattern types: | ||||
| 365 | + | ||||
| 366 | +| Pattern | Meaning | Example | Matches | | ||||
| 367 | +| - | - | - | - | | ||||
| 368 | +| `//path` | Absolute path from filesystem root | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` | | ||||
| 369 | +| `~/path` | Path from home directory | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` | | ||||
| 370 | +| `/path` | Path relative to the settings source | `Edit(/src/**/*.ts)` | `<primary working directory>/src/**/*.ts` in project settings | | ||||
| 371 | +| `path` or `./path` | Path relative to current directory | `Read(*.env)` | `<cwd>/*.env` | | ||||
| 372 | + | ||||
| 373 | +> [!WARNING] | ||||
| 374 | +> | ||||
| 375 | +> A pattern like `/Users/alice/file` isn't an absolute path. The single leading slash anchors at the settings source, not the filesystem root. Use `//Users/alice/file` for absolute paths. | ||||
| 376 | + | ||||
| 377 | +##### Where a pattern anchors | ||||
| 378 | + | ||||
| 379 | +A `/path` pattern anchors at a directory associated with the settings source that defines it, so the same rule matches different locations depending on where you put it: | ||||
| 380 | + | ||||
| 381 | +| Rule defined in | `/path` resolves to | | ||||
| 382 | +| :- | :- | | ||||
| 383 | +| Project settings at `.claude/settings.json` | `<primary working directory>/path` | | ||||
| 384 | +| Local settings at `.claude/settings.local.json` | `<primary working directory>/path` | | ||||
| 385 | +| User settings at `~/.claude/settings.json` | `~/.claude/path` | | ||||
| 386 | +| A file passed with `--settings <file>` | `<directory of file>/path` | | ||||
| 387 | +| CLI flags or session rules | `<primary working directory>/path` | | ||||
| 388 | + | ||||
| 389 | +A rule you add through `/permissions` follows the row for the settings file you save it to. | ||||
| 390 | + | ||||
| 391 | +Local settings rules anchor at the session's [primary working directory](#working-directories), not at the repository root where Claude Code [stores the file](#permission-system). In a session started at the repository root, the two directories are the same; in a [worktree](https://code.claude.com/docs/en/worktrees.md) session, a shared rule such as `Edit(/src/**)` matches that worktree's own `src/` directory. | ||||
| 392 | + | ||||
| 393 | +A deny rule such as `Read(/secrets/**)` in user settings blocks `~/.claude/secrets/**`, not a `secrets` directory in your project. To write a rule in user settings that applies inside every project, use a `//` absolute path or a `~/` home-relative path instead. | ||||
| 394 | + | ||||
| 395 | +On Windows, paths are normalized to POSIX form before matching. `C:\Users\alice` becomes `/c/Users/alice`, so use `//c/**/.env` to match `.env` files anywhere on that drive. To match across all drives, use `//**/.env`. | ||||
| 396 | + | ||||
| 397 | +Examples: | ||||
| 398 | + | ||||
| 399 | +* `Edit(/docs/**)`: edits in `<primary working directory>/docs/`, not `/docs/` or `<primary working directory>/.claude/docs/` | ||||
| 400 | +* `Read(~/.zshrc)`: reads your home directory's `.zshrc` | ||||
| 401 | +* `Edit(//tmp/scratch.txt)`: edits the absolute path `/tmp/scratch.txt` | ||||
| 402 | +* `Read(src/**)`: as an allow rule, reads from `<current-directory>/src/` only; as a deny or ask rule, matches a `src` directory at any depth under the current directory | ||||
| 403 | + | ||||
| 404 | +##### How deep a pattern matches | ||||
| 405 | + | ||||
| 406 | +A rule only matches files under its anchor; within that bound, matching depth depends on the pattern shape and, for single-segment directory patterns, the rule type, described below. Bare filenames follow gitignore semantics and match at any depth, so `Read(.env)` and `Read(**/.env)` are equivalent: | ||||
| 407 | + | ||||
| 408 | +| Deny rule | Blocks | Does not block | | ||||
| 409 | +| - | - | - | | ||||
| 410 | +| `Read(.env)` or `Read(**/.env)` | any `.env` at or under the current directory | `.env` in a parent directory or another project | | ||||
| 411 | +| `Read(//**/.env)` | any `.env` anywhere on the filesystem | nothing; the rule is anchored at the filesystem root | | ||||
| 412 | + | ||||
| 413 | +A relative pattern with a single directory segment, such as `src/**`, matches at different depths depending on the rule type: | ||||
| 414 | + | ||||
| 415 | +* **Allow rules**: `Edit(src/**)` matches only `<cwd>/src` and the files under it. To allow a directory name at any depth, write `Edit(**/src/**)`. | ||||
| 416 | +* **Deny and ask rules**: `Read(secrets/**)` matches a directory named `secrets` at any depth under the current directory, so the rule also applies to nested copies. | ||||
| 417 | + | ||||
| 418 | +Every other pattern shape matches at the same depth in every rule type: `Edit(/src/**)` and `Edit(src/components/**)` match only at their anchored location, while `Edit(**/src/**)` matches at any depth. | ||||
| 419 | + | ||||
| 420 | +The following example shows each pattern shape against a project with a top-level `src/` directory and a nested copy under `vendor/`: | ||||
| 421 | + | ||||
| 422 | +```text theme={null} | ||||
| 423 | +<current-directory>/ | ||||
| 424 | +├── src/ | ||||
| 425 | +│ └── app.ts | ||||
| 426 | +└── vendor/ | ||||
| 427 | + └── pkg/ | ||||
| 428 | + └── src/ | ||||
| 429 | + └── lib.js | ||||
| 430 | +``` | ||||
| 431 | + | ||||
| 432 | +| Rule | Matches `src/app.ts` | Matches `vendor/pkg/src/lib.js` | | ||||
| 433 | +| :- | :- | :- | | ||||
| 434 | +| `Edit(src/**)` as an allow rule | Yes | No | | ||||
| 435 | +| `Edit(src/**)` as a deny or ask rule | Yes | Yes | | ||||
| 436 | +| `Edit(/src/**)` in any rule type | Yes | No | | ||||
| 437 | +| `Edit(**/src/**)` in any rule type | Yes | Yes | | ||||
| 438 | + | ||||
| 439 | +> [!NOTE] | ||||
| 440 | +> | ||||
| 441 | +> In gitignore patterns, `*` matches within a single path segment and can appear at any position in the pattern, while `**` matches across directories. | ||||
| 442 | + | ||||
| 443 | +#### Special characters and `!` negation | ||||
| 444 | + | ||||
| 445 | +When you approve a file path with "Yes, and don't ask again", Claude Code escapes gitignore pattern characters in that path, such as `[`, `]`, and `*`, so the generated rule matches only the literal path you approved. Rules you write yourself aren't escaped. | ||||
| 446 | + | ||||
| 447 | +You don't need to escape parentheses in a path, so `Edit(./Finance (2024)/**)` matches the `Finance (2024)` folder as spelled. | ||||
| 448 | + | ||||
| 449 | +A deny or ask rule whose path isn't usable as a gitignore pattern still guards that exact path. An allow rule with an unusable pattern doesn't approve anything. | ||||
| 450 | + | ||||
| 451 | +A deny or ask pattern that starts with `!` is a gitignore negation. It carves the paths it matches out of the `path` or `./path` rules listed before it. In one settings file's `deny` list, `Read(*.env)` followed by `Read(!sample.env)` blocks every file whose name ends in `.env` at any depth, except files named `sample.env`. A `!` rule listed first carves nothing out. | ||||
| 452 | + | ||||
| 453 | +The carve-out reaches only rules from the same source. A `Read(!.env)` in project settings or in `--disallowedTools` doesn't cancel a `Read(./.env)` deny from managed settings or any other settings file. | ||||
| 454 | + | ||||
| 455 | +Two limits narrow what a `!` pattern can carve out: | ||||
| 456 | + | ||||
| 457 | +* Claude Code reads a `!` pattern relative to the current directory even when `/`, `~/`, or `//` follows the `!`, so the pattern can't reach a rule anchored with one of those prefixes. `Read(!~/notes/public/**)` carves nothing out of `Read(~/notes/**)`. | ||||
| 458 | +* A carve-out can't reopen a file inside a directory that a rule blocks as a whole. With `Read(secrets/**)` and `Read(!secrets/public/**)`, Claude Code still blocks `secrets/public` along with the rest of `secrets`. | ||||
| 459 | + | ||||
| 460 | +#### Symlinks | ||||
| 461 | + | ||||
| 462 | +When a file path Claude requests goes through a symlink, the permission check covers two paths: the one Claude requested and the file it resolves to. This applies to symbolic links on macOS, Linux, and Windows, and to directory junctions on Windows. | ||||
| 463 | + | ||||
| 464 | +##### How rules match a symlinked path | ||||
| 465 | + | ||||
| 466 | +Allow and deny rules treat the requested path and the file it resolves to differently: | ||||
| 467 | + | ||||
| 468 | +* **Allow rules**: apply only when both the requested path and the file it resolves to match. A read through a symlink inside an allowed directory that points outside it doesn't match the rule. | ||||
| 469 | +* **Deny rules**: apply when either the requested path or the file it resolves to matches. A symlink that points to a denied file is itself denied. For example, with `Read(./project/**)` allowed and `Read(~/.ssh/**)` denied, a symlink at `./project/key` pointing to `~/.ssh/id_rsa` is blocked: the target fails the allow rule and matches the deny rule. | ||||
| 470 | + | ||||
| 471 | +On macOS and Linux, a deny or ask rule written through a symlinked directory with a `//`, `~/`, or `/` pattern also applies at the directory's real location. For example, on macOS, where `/etc` resolves to `/private/etc`, `Read(//etc/**)` blocks `/private/etc/hosts` too. Before v2.1.268, a deny or ask rule written through a symlinked directory didn't apply to a path given by its real location. | ||||
| 472 | + | ||||
| 473 | +Grep and Glob search the directory the `path` argument resolves to. Claude Code applies `Read` deny rules to that directory. | ||||
| 474 | + | ||||
| 475 | +##### Attachments through a symlink | ||||
| 476 | + | ||||
| 477 | +A `Read` deny rule also covers these attachments, matching each one on either the named path or the file it resolves to. Claude Code leaves an attachment out of the conversation when a rule matches it: | ||||
| 478 | + | ||||
| 479 | +* **`@`-mentions**: a file or directory you mention in your prompt. A refused file leaves nothing in the conversation, and a [directory's listing](#read-and-edit) leaves out the names a rule covers. | ||||
| 480 | +* **Pasted images**: an image whose path you paste or drag into the prompt in the terminal | ||||
| 481 | +* **Changed files**: a file Claude Code re-reads after it changes on disk | ||||
| 482 | +* **IDE context**: the selection and open-file context a connected IDE shares | ||||
| 483 | + | ||||
| 484 | +With [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories) on, or in a [`--restricted`](https://code.claude.com/docs/en/cli-reference#cli-flags) session, these attachments are also left out when they come from a path where that setting or flag refuses Claude's file reads. | ||||
| 485 | + | ||||
| 486 | +This line in place of a file you `@`-mentioned means Claude Code couldn't work out where the path leads, for example because its symlinks form a loop: | ||||
| 487 | + | ||||
| 488 | +```text theme={null} | ||||
| 489 | +Referenced <path> (not read: could not be examined) | ||||
| 490 | +``` | ||||
| 491 | + | ||||
| 492 | +Claude is told to read the path with its file tools instead, which can succeed when Claude Code only ran out of time to examine the path. | ||||
| 493 | + | ||||
| 494 | +When the path's symlinks don't resolve, that read is [refused](https://code.claude.com/docs/en/errors.md#refusing-after-a-symlink-changed) too, so fix the link on disk or `@`-mention the file by a path that resolves. | ||||
| 495 | + | ||||
| 496 | +##### Writes through a symlink | ||||
| 497 | + | ||||
| 498 | +If the path Claude asks to edit or write is itself a symlink, the Edit and Write tools [refuse the write and direct Claude to the link's target](https://code.claude.com/docs/en/errors.md#refusing-after-a-symlink-changed). | ||||
| 499 | + | ||||
| 500 | +A write can still pass through a symlink when a directory on the way to the file is a symlink, or when a Bash or PowerShell command does the writing. For those writes, what happens depends on where the file the write resolves to sits relative to your [working directories](#working-directories) and the [protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths): | ||||
| 501 | + | ||||
| 502 | +* **Resolves outside the working directories**: when the requested path is inside your working directories and the file it resolves to isn't, the write isn't auto-approved in [`acceptEdits` mode](https://code.claude.com/docs/en/permission-modes#auto-approve-file-edits-with-acceptedits-mode). In [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), unless an allow rule approves the write, you're prompted for it instead of the classifier deciding. The prompt names the path the write resolves to. | ||||
| 503 | +* **Resolves to a protected path that the requested path doesn't name**: the [protected paths table](https://code.claude.com/docs/en/permission-modes.md#protected-paths) gives the outcome for each permission mode, except that where the table routes the write to the classifier, this write prompts you instead. | ||||
| 504 | + | ||||
| 505 | +##### Paths that can't be resolved or that change | ||||
| 506 | + | ||||
| 507 | +When Claude Code can't determine where a path leads on disk, for example because symlinks on it form a loop, the Read, Edit, and Write tools [refuse the operation](https://code.claude.com/docs/en/errors.md#refusing-after-a-symlink-changed). | ||||
| 508 | + | ||||
| 509 | +When a tool then opens the approved file, it [confirms that the path still resolves to the location the permission check approved](https://code.claude.com/docs/en/errors.md#refusing-after-a-symlink-changed). | ||||
| 510 | + | ||||
| 511 | +#### Network paths | ||||
| 512 | + | ||||
| 513 | +When Claude's file-reading tools, such as Read, Grep, and Glob, read from a network path, the read gets its own permission check. A network path is one that can reach another computer: on Windows, a UNC path such as `\\server\share\file`, and on macOS and Linux, a `/net` automount path such as `/net/fileserver/notes.txt`. Looking up such a path can contact the host it names, and on Windows that contact can send the host your credentials. Shell commands have their own check: in Manual mode, a read-only Bash or PowerShell command whose arguments include a UNC path [still prompts on Windows](#read-only-commands). | ||||
| 514 | + | ||||
| 515 | +In Claude Code v2.1.292 and later, each of these leaves the prompt in place: | ||||
| 516 | + | ||||
| 517 | +* **Allow rules**: a rule doesn't pre-approve the read, including a rule for the whole tool, such as `Read` | ||||
| 518 | +* **PreToolUse hooks**: a [hook](#extend-permissions-with-hooks) that returns `"allow"` doesn't skip the prompt | ||||
| 519 | +* **Auto mode**: the prompt comes to you, and the [classifier](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) doesn't decide the read | ||||
| 520 | + | ||||
| 521 | +In `dontAsk` mode, Claude Code denies the read instead of prompting. In `bypassPermissions` mode, and in interactive terminal sessions in plan mode with [bypass permissions](https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) available, the read runs without this prompt. | ||||
| 522 | + | ||||
| 523 | +To read files on a network share without this prompt, give the share a local path first: | ||||
| 524 | + | ||||
| 525 | +* **Windows**: map the share to a drive letter and pass the drive with `--add-dir` when you launch Claude Code, as [Working directories](#working-directories) describes. For a share mapped to `Z:`, run `claude --add-dir Z:\` in PowerShell. | ||||
| 526 | +* **macOS and Linux**: mount the share at a local path, such as a directory under `/mnt` or `/Volumes`, and read the files from there, as [Working directory is a network path](https://code.claude.com/docs/en/errors.md#working-directory-is-a-network-path) describes | ||||
| 527 | + | ||||
| 528 | +### WebFetch | ||||
| 529 | + | ||||
| 530 | +WebFetch rules use a `domain:` prefix and match against the hostname of the requested URL. Matching is case-insensitive, supports `*` wildcards, and strips a trailing `.` from both the rule and the hostname so `example.com.` and `example.com` are treated the same. | ||||
| 531 | + | ||||
| 532 | +* `WebFetch(domain:example.com)` matches requests to `example.com` only. To also cover subdomains such as `api.example.com`, add a `WebFetch(domain:*.example.com)` rule | ||||
| 533 | +* `WebFetch(domain:*.example.com)` matches any subdomain at any depth, such as `api.example.com` or `a.b.example.com`, but not `example.com` itself | ||||
| 534 | +* `WebFetch(domain:*)` matches every domain. It isn't the same as a bare `WebFetch` rule; see [Allow or deny every fetch](#allow-or-deny-every-fetch) | ||||
| 535 | + | ||||
| 536 | +In any position other than a leading `*.` or a bare `*`, the wildcard matches only the text between two dots. `WebFetch(domain:example.*)` matches `example.org`, where `*` becomes `org`, but not `example.evil.com`, where `*` would have to become `evil.com` and cross a dot. This keeps a trailing wildcard from matching domains an attacker could register. | ||||
| 537 | + | ||||
| 538 | +Wildcards in `WebFetch` rules require Claude Code v2.1.172 or later to match fetches. | ||||
| 539 | + | ||||
| 540 | +#### Allow or deny every fetch | ||||
| 541 | + | ||||
| 542 | +A bare `WebFetch` rule is the tool name with no `domain:` part, such as `"deny": ["WebFetch"]`. Both it and `WebFetch(domain:*)` cover every URL, but Claude Code applies them differently, and only the `domain:` form also adds its domain to the sandbox's [allowed or denied domain list](https://code.claude.com/docs/en/sandboxing.md#network-isolation). That section lists the wildcard forms the sandbox honors and the version that added bare `*`. | ||||
| 543 | + | ||||
| 544 | +Each row shows what a rule does in the `allow` list and in the `deny` list: | ||||
| 545 | + | ||||
| 546 | +| Rule | In `allow` | In `deny` | | ||||
| 547 | +| :- | :- | :- | | ||||
| 548 | +| `WebFetch` | Claude fetches without prompting you. Doesn't change which hosts sandboxed commands can reach. | Claude Code removes the `WebFetch` tool, so Claude can't fetch at all. Doesn't change which hosts sandboxed commands can reach. | | ||||
| 549 | +| `WebFetch(domain:*)` | Claude fetches without prompting you, and sandboxed commands can reach any host. | Claude Code keeps the tool and refuses each fetch, and sandboxed commands can't reach any host. | | ||||
| 550 | + | ||||
| 551 | +The two forms also differ on reads of [artifacts](https://code.claude.com/docs/en/artifacts.md), the pages the Artifact tool publishes on claude.ai. A bare `WebFetch` deny or ask rule doesn't apply to those reads. A `domain:` rule covering `claude.ai` or the `*.claudeusercontent.com` content host, such as `WebFetch(domain:claude.ai)` or `WebFetch(domain:*)`, denies each read or prompts before it. An [`Artifact` rule](https://code.claude.com/docs/en/artifacts#disable-artifacts) does the same. | ||||
| 552 | + | ||||
| 553 | +When a rule blocks a read, the denial names the rule. Before v2.1.268, a bare `WebFetch` deny rule blocked every artifact read, and a bare ask rule prompted before each one. | ||||
| 554 | + | ||||
| 555 | +To let Claude fetch freely while keeping the sandbox allowlist as it is, use the bare form. This `settings.json` does that: | ||||
| 556 | + | ||||
| 557 | +```json theme={null} | ||||
| 558 | +{ | ||||
| 559 | + "permissions": { | ||||
| 560 | + "allow": ["WebFetch"] | ||||
| 561 | + } | ||||
| 562 | +} | ||||
| 563 | +``` | ||||
| 564 | + | ||||
| 565 | +When you ask Claude to fetch a page, it fetches without a prompt. When you ask it to run a [sandboxed](https://code.claude.com/docs/en/sandboxing.md) `curl` against a host outside the sandbox allowlist, Claude Code still prompts you for that host, because the bare rule didn't add the host to the allowlist. | ||||
| 566 | + | ||||
| 567 | +In [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), Claude instead names the host in the command's [per-command allowed domains](https://code.claude.com/docs/en/sandboxing.md#per-command-allowed-domains-in-auto-mode) for the classifier to review. | ||||
| 568 | + | ||||
| 569 | +### MCP | ||||
| 570 | + | ||||
| 571 | +To match every tool from an MCP server, write `mcp__<server>__*`. To match one tool, write its full name, `mcp__<server>__<tool>`. | ||||
| 572 | + | ||||
| 573 | +* `mcp__puppeteer` matches any tool provided by the `puppeteer` server | ||||
| 574 | +* `mcp__puppeteer__*` uses wildcard syntax and also matches all tools from the `puppeteer` server | ||||
| 575 | +* `mcp__puppeteer__puppeteer_navigate` matches the `puppeteer_navigate` tool provided by the `puppeteer` server | ||||
| 576 | + | ||||
| 577 | +For `<server>`, write the server's name the way it appears in that server's tool names. These examples show the rule to write for a name with special characters, a server from a plugin, and a name that contains `__` or ends in `_`: | ||||
| 578 | + | ||||
| 579 | +* **Names with characters such as `.` or spaces**: those characters become `_`, so for a server you configured as `my.server`, write `mcp__my_server__*` | ||||
| 580 | +* **Servers that a plugin provides**: `<server>` takes the [plugin-scoped form](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers), so for the `database-tools` server in a plugin named `my-plugin`, write `mcp__plugin_my-plugin_database-tools__*` | ||||
| 581 | +* **A `<server>` that contains `__` or ends in `_`**: write the wildcard form, `mcp__<server>__*`, with the whole name. For a server named `reports__v2`, write `mcp__reports__v2__*`. The bare `mcp__reports__v2` and the shorter `mcp__reports` don't match its tools as allow rules, because Claude Code reads both as rules for a server named `reports`. | ||||
| 582 | + | ||||
| 583 | + As a deny or ask rule, though, each of those two names also covers every tool of the `reports__v2` server. To cover a server named `reports` alone, write one rule per tool in the `mcp__reports__<tool>` form, or rename one of the servers. | ||||
| 584 | + | ||||
| 585 | +If your organization has set a [claude.ai connector](https://code.claude.com/docs/en/mcp.md#organization-controls-on-connector-tools) tool to `ask` and that setting reaches Claude Code in your session, allow rules for that tool don't take effect: Claude Code prompts on every call, even in `auto` and `bypassPermissions` modes. In `dontAsk` mode, which never prompts, Claude Code denies the call instead. Tools from connectors Claude Code fetches itself appear as `mcp__claude_ai_<server>__<tool>`. | ||||
| 586 | + | ||||
| 587 | +In a [Cowork](https://claude.com/docs/cowork/overview) session in the Claude Desktop app, Claude runs shell commands through Cowork's `mcp__workspace__bash` tool rather than the built-in `Bash` tool, and Cowork likewise provides `mcp__workspace__web_fetch` for web fetches. Claude Code also applies deny rules that name the whole `Bash` or `WebFetch` tool to these Cowork tools, so a managed `Bash` deny rule stops Claude from running shell commands in Cowork. When Claude Code blocks such a call, the message names the Cowork tool: `Permission to use mcp__workspace__bash has been denied.` Allow rules don't carry over: Claude Code never applies a `Bash` allow rule to `mcp__workspace__bash`. | ||||
| 588 | + | ||||
| 589 | +### Agent (subagents) | ||||
| 590 | + | ||||
| 591 | +Use `Agent(AgentName)` rules to control which [subagents](https://code.claude.com/docs/en/sub-agents.md) Claude can use: | ||||
| 592 | + | ||||
| 593 | +* `Agent(Explore)` matches the Explore subagent | ||||
| 594 | +* `Agent(Plan)` matches the Plan subagent | ||||
| 595 | +* `Agent(my-custom-agent)` matches a custom subagent named `my-custom-agent` | ||||
| 596 | + | ||||
| 597 | +Add these rules to the `deny` array in your settings or use the `--disallowedTools` CLI flag to disable specific agents. To disable the Explore agent: | ||||
| 598 | + | ||||
| 599 | +```json theme={null} | ||||
| 600 | +{ | ||||
| 601 | + "permissions": { | ||||
| 602 | + "deny": ["Agent(Explore)"] | ||||
| 603 | + } | ||||
| 604 | +} | ||||
| 605 | +``` | ||||
| 606 | + | ||||
| 607 | +### Cd | ||||
| 608 | + | ||||
| 609 | +`Cd` rules control which directories the [`/cd` command](https://code.claude.com/docs/en/commands) can move the session to. `Cd` is not a model-invocable tool: Claude can't call it, and the rules apply only when you run `/cd` yourself. | ||||
| 610 | + | ||||
| 611 | +A bare `Cd` deny rule disables `/cd` entirely. A `Cd(<path-pattern>)` deny rule blocks matching targets. Deny rules check every spelling of the target, including each symlink hop it resolves through, so a rule written for one path also blocks targets that resolve to it. | ||||
| 612 | + | ||||
| 613 | +Adding any `Cd` allow rule switches `/cd` to allowlist mode: the resolved target directory must match one of your allow rules, or `/cd` refuses. With no `Cd` rules configured, `/cd` keeps its default behavior and prompts you to trust an unfamiliar directory. | ||||
| 614 | + | ||||
| 615 | +Path patterns share the `//`, `~/`, and `/` anchors from [Read and Edit rules](#read-and-edit), but matching is anchored to the whole directory path rather than gitignore-style. `*` matches exactly one path segment and `**` matches across segments. A trailing `/**` also matches its named root. | ||||
| 616 | + | ||||
| 617 | +| Rule | Matches | Does not match | | ||||
| 618 | +| - | - | - | | ||||
| 619 | +| `Cd(~/code/*)` | `~/code/app` | `~/code/app/src`, `~/code` | | ||||
| 620 | +| `Cd(~/code/**)` | `~/code` and any directory under it | directories outside `~/code` | | ||||
| 621 | +| `Cd(**/node_modules)` | any `node_modules` directory at any depth under the current directory | `node_modules/pkg` | | ||||
| 622 | + | ||||
| 623 | +## Extend permissions with hooks | ||||
| 624 | + | ||||
| 625 | +[Claude Code hooks](https://code.claude.com/docs/en/hooks-guide.md) let you register custom shell commands that evaluate permissions at runtime. When Claude Code makes a tool call, PreToolUse hooks run before the permission prompt, for every tool except [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior). The hook output can deny the tool call, force a prompt, or skip the prompt to let the call proceed. | ||||
| 626 | + | ||||
| 627 | +### Precedence among rules, hooks, and mods | ||||
| 628 | + | ||||
| 629 | +PreToolUse hook decisions don't bypass permission rules. Claude Code evaluates deny and ask rules regardless of what a PreToolUse hook returns: a matching deny rule blocks the call, and a matching ask rule still prompts even when the hook returned `"allow"` or `"ask"`. This preserves the deny-first precedence described in [Manage permissions](#manage-permissions), including deny rules set in managed settings. | ||||
| 630 | + | ||||
| 631 | +That precedence covers hooks in settings files and in a plugin's `hooks/hooks.json`. A [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you install that handles the [`tool.check`](https://code.claude.com/docs/en/plugins/mods/events#approve-or-refuse-a-tool-call-before-the-user-is-asked) event gives its answer after the `PreToolUse` hooks have run. With [managed settings](https://code.claude.com/docs/en/settings.md#check-what-your-organization-enforces) on the machine, or a Team or Enterprise [`/login`](https://code.claude.com/docs/en/authentication#authentication-precedence) as the session's credential, these outcomes stay in place by default when the mod approves a call: | ||||
| 632 | + | ||||
| 633 | +* A call that a deny rule refuses stays refused, and your organization can change that. | ||||
| 634 | +* A call that an ask rule would prompt for still prompts you. | ||||
| 635 | +* A call that a `PreToolUse` hook or [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories) would prompt for still prompts you. | ||||
| 636 | +* A call that a `PreToolUse` hook blocked stays blocked, whichever settings file the hook comes from. | ||||
| 637 | +* A call that your [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags) or Agent SDK [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/user-input#handle-tool-approval-requests) would be asked about is still put to that tool or callback. | ||||
| 638 | + | ||||
| 639 | +With neither managed settings nor a Team or Enterprise `/login` as the session's credential, the mod can approve a call that a deny rule refuses or a `PreToolUse` hook blocked. A session that runs on an API key or a long-lived [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/en/authentication#generate-a-long-lived-token) instead isn't using that login, even when that login is stored. | ||||
| 640 | + | ||||
| 641 | +In that setup you aren't prompted when the mod approves a call that an ask rule, a `PreToolUse` hook, or `permissions.blockReadsOutsideWorkingDirectories` would prompt for. Your `--permission-prompt-tool` or `canUseTool` callback isn't asked about a call the mod approves, either. Auto mode, plan mode, and `dontAsk` mode each add an outcome of their own in every setup: | ||||
| 642 | + | ||||
| 643 | +* **[Auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)**: a call the mod approves runs without a classifier check, except where the mod can't bypass your permission prompt tool or Agent SDK permission callback. There the classifier checks the call first. | ||||
| 644 | +* **[Plan mode](#hook-approvals-in-plan-mode)**: the mod can't approve a call that isn't read-only, such as a file edit or a shell command that writes. | ||||
| 645 | +* **[`dontAsk` mode](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)**: the mod can approve a call that nothing but the mode would deny. | ||||
| 646 | + | ||||
| 647 | +See [Decide whether to trust a mod](https://code.claude.com/docs/en/plugins/mods/overview.md#decide-whether-to-trust-a-mod), or [Manage mods for your organization](https://code.claude.com/docs/en/plugins/mods/admin.md#know-what-happens-by-default) if you deploy managed settings. | ||||
| 648 | + | ||||
| 649 | +For a [tool that requires user interaction](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves), such as `AskUserQuestion` or an MCP tool marked `requiresUserInteraction`, a mod's `tool.check` approval doesn't skip the prompt. Requires Claude Code v2.1.292 or later. MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) also still prompt when a hook returns `"allow"`, as do reads from [network paths](#network-paths) and connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code. | ||||
| 650 | + | ||||
| 651 | +A blocking hook also takes precedence over allow rules. A hook that exits with code 2 stops the tool call before permission rules are evaluated, so the block applies even when an allow rule would otherwise let the call proceed. To run all Bash commands without prompts except for a few you want blocked, add `"Bash"` to your allow list and register a PreToolUse hook that rejects those specific commands. See [Block edits to protected files](https://code.claude.com/docs/en/hooks-guide.md#block-edits-to-protected-files) for a hook script you can adapt. | ||||
| 652 | + | ||||
| 653 | +### Hook approvals in plan mode | ||||
| 654 | + | ||||
| 655 | +In [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode), apart from `ExitPlanMode`, your `PreToolUse` hook's `"allow"` has no effect on a file edit or another call that isn't read-only. You get the same prompt, block, or approval the call would get with no hook, and Claude Code still applies any `updatedInput` the hook returns. If the hook answers [`ExitPlanMode`](https://code.claude.com/docs/en/hooks#allow-with-updatedinput) with `"allow"` and `updatedInput`, that tool still runs without a prompt. | ||||
| 656 | + | ||||
| 657 | +In plan mode, a mod that handles `tool.check` also can't approve a file edit or another call that isn't read-only, though it can still block such a call. To lift this limit on hook and mod approvals, [approve the plan](https://code.claude.com/docs/en/permission-modes.md#review-and-approve-a-plan) or switch to another permission mode. | ||||
| 658 | + | ||||
| 659 | +## Working directories | ||||
| 660 | + | ||||
| 661 | +By default, Claude has access to files in the directory where you launched it. That directory is the session's primary working directory until you [move the session with `/cd`](#move-the-session-to-another-directory). You can extend this access: | ||||
| 662 | + | ||||
| 663 | +* **During startup**: use `--add-dir <path>` CLI argument | ||||
| 664 | +* **During session**: use `/add-dir` command | ||||
| 665 | +* **Persistent configuration**: add to `additionalDirectories` in [settings files](https://code.claude.com/docs/en/settings.md#where-settings-live) | ||||
| 666 | + | ||||
| 667 | +Files in additional directories follow the same permission rules as the original working directory: they become readable without prompts apart from the [network path](#network-paths) check, and file editing permissions follow the current permission mode. | ||||
| 668 | + | ||||
| 669 | +You can't add most [network paths](https://code.claude.com/docs/en/errors.md#working-directory-is-a-network-path), such as the UNC share `\\server\share`, as working directories, because looking one up can contact the host it names. On Windows, map the share to a drive letter instead and pass the drive with `--add-dir` at launch. | ||||
| 670 | + | ||||
| 671 | +Set [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories) to make the file tools refuse the paths it fences in every permission mode. In auto mode, Claude Code offers to turn it on the first time Claude [reads outside the working directories](https://code.claude.com/docs/en/permission-modes.md#first-read-outside-the-working-directories). | ||||
| 672 | + | ||||
| 673 | +In background sessions on macOS, the session host requests access to protected folders such as `~/Desktop`, `~/Documents`, and `~/Downloads` separately from your terminal when Claude needs to read or write files there; if reads there fail with `Operation not permitted`, see [how to grant folder access to background sessions](https://code.claude.com/docs/en/agent-view.md#background-sessions-can’t-read-desktop-documents-or-downloads-on-macos). | ||||
| 674 | + | ||||
| 675 | +### Move the session to another directory | ||||
| 676 | + | ||||
| 677 | +To move the session to a different primary working directory, rather than [adding a directory](#working-directories) alongside the current one, run `/cd <path>`. Claude Code keeps the conversation, loads the new directory's `CLAUDE.md`, and prompts you to [trust the workspace](#project-allow-rules-and-workspace-trust) if you haven't worked in it before. Afterward, Claude Code [finds the moved session](https://code.claude.com/docs/en/sessions.md#where-the-session-picker-looks) when you run `--resume` from the new directory. | ||||
| 678 | + | ||||
| 679 | +As soon as you move, Claude Code applies the new directory's project configuration: | ||||
| 680 | + | ||||
| 681 | +* Its project settings, including their permission rules and [hooks](https://code.claude.com/docs/en/hooks.md) | ||||
| 682 | +* Its [`.mcp.json` servers](https://code.claude.com/docs/en/mcp#project-scope), subject to the same [server approval](https://code.claude.com/docs/en/mcp.md#project-server-approvals-and-workspace-trust) as at startup, and the [local-scope](https://code.claude.com/docs/en/mcp.md#local-scope) MCP servers you registered in it | ||||
| 683 | +* The [plugins](https://code.claude.com/docs/en/plugins/overview.md) its settings enable, its [skills](https://code.claude.com/docs/en/skills.md#discovery-from-parent-and-nested-directories), and its [subagents](https://code.claude.com/docs/en/sub-agents.md) | ||||
| 684 | +* Its [`env`](https://code.claude.com/docs/en/settings-reference#env) values, applied on top of the environment variables from the previous directory's settings, which stay in effect | ||||
| 685 | + | ||||
| 686 | +Claude Code also disconnects the previous directory's project and [local-scope](https://code.claude.com/docs/en/mcp.md#local-scope) MCP servers, and the servers of [plugins](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) that are no longer enabled after the move. It takes [additional directories](#working-directories) from the new directory's settings instead of the previous one's, and keeps the directories you added with `--add-dir` or `/add-dir`. Hooks the move activates still receive [`${CLAUDE_PROJECT_DIR}`](https://code.claude.com/docs/en/hooks#reference-scripts-by-path) set to the project root where the session started. | ||||
| 687 | + | ||||
| 688 | +When the new directory isn't trusted yet, Claude Code lists in the trust prompt the allow rules, additional directories, hooks, and helper commands the directory's settings would activate, so you can review them before you accept. If you decline, the session stays where it is. Before v2.1.246, `/cd` didn't apply the new directory's settings, hooks, MCP servers, or skills until you resumed the session, and its trust prompt didn't list what the directory's settings would activate. | ||||
| 689 | + | ||||
| 690 | +Restrict or disable `/cd` targets with [`Cd` permission rules](#cd). | ||||
| 691 | + | ||||
| 692 | +### Additional directories grant file access, not configuration | ||||
| 693 | + | ||||
| 694 | +Adding a directory extends where Claude can read and edit files. It doesn't make that directory a full configuration root: most `.claude/` configuration is not discovered from additional directories, though a few types are loaded as exceptions. | ||||
| 695 | + | ||||
| 696 | +These exceptions apply only to directories added with the `--add-dir` flag or the `/add-dir` command, including directories the Agent SDK adds through the flag. Directories listed in `permissions.additionalDirectories` in a settings file grant file access only and don't load any of the configuration below. | ||||
| 697 | + | ||||
| 698 | +The Agent SDK's [`additionalDirectories`](https://code.claude.com/docs/en/agent-sdk/typescript#options) option in TypeScript and [`add_dirs`](https://code.claude.com/docs/en/agent-sdk/python#claudeagentoptions) option in Python receive the exceptions too, even though the TypeScript option shares its name with the settings key. The SDK passes each entry to Claude Code as `--add-dir`, so those directories behave like flag-added directories. Skills, commands, and subagents from any flag-added directory load through the `project` [setting source](https://code.claude.com/docs/en/agent-sdk/claude-code-features.md#control-filesystem-settings-with-settingsources), so they don't load when you exclude that source with [`--setting-sources`](https://code.claude.com/docs/en/cli-reference) on the CLI or `settingSources` in the SDK, and [bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode) skips the commands and subagents among them. | ||||
| 699 | + | ||||
| 700 | +The following configuration types are loaded from `--add-dir` directories: | ||||
| 701 | + | ||||
| 702 | +| Configuration | Loaded from `--add-dir` | | ||||
| 703 | +| :- | :- | | ||||
| 704 | +| [Skills](https://code.claude.com/docs/en/skills.md) in `.claude/skills/` | Yes, with live reload | | ||||
| 705 | +| [Command files](https://code.claude.com/docs/en/skills.md#where-skills-live) in `.claude/commands/` | Yes, without live reload. When the added directory and your project both define a command with the same name, Claude Code runs your project's command | | ||||
| 706 | +| [Subagents](https://code.claude.com/docs/en/sub-agents.md) in `.claude/agents/` | Yes, without live reload | | ||||
| 707 | +| [Settings](https://code.claude.com/docs/en/settings.md) in `.claude/settings.json` and `.claude/settings.local.json` | `enabledPlugins` and [`extraKnownMarketplaces`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces) keys only | | ||||
| 708 | +| [CLAUDE.md](https://code.claude.com/docs/en/memory.md) files, `.claude/rules/`, and `CLAUDE.local.md` | Only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set. `CLAUDE.local.md` additionally requires the `local` setting source, which is enabled by default | | ||||
| 709 | + | ||||
| 710 | +To load the skills, commands, and subagents from a subdirectory of your [primary working directory](#working-directories) mid-session, run `/add-dir` with that subdirectory's path. Claude Code loads them for the rest of the session without prompting you or adding a working directory, because the subdirectory is already readable. This requires Claude Code v2.1.257 or later. | ||||
| 711 | + | ||||
| 712 | +#### Where output styles, hooks, and local settings load from | ||||
| 713 | + | ||||
| 714 | +Claude Code discovers output styles from the current working directory and its parents, your user directory at `~/.claude/`, and managed settings. Hooks and other `.claude/settings.json` keys load from the current working directory's `.claude/` folder with no parent-directory fallback, alongside your user `~/.claude/settings.json` and managed settings. | ||||
| 715 | + | ||||
| 716 | +`.claude/settings.local.json` loads from the git repository root instead, even when you start Claude Code in a subdirectory, except where Claude Code [doesn't use the repository root](https://code.claude.com/docs/en/settings.md#where-claude-code-looks-for-each-file), such as on Windows. | ||||
| 717 | + | ||||
| 718 | +To share that configuration across projects, use one of these approaches: | ||||
| 719 | + | ||||
| 720 | +* **User-level configuration**: place files in `~/.claude/agents/`, `~/.claude/output-styles/`, or `~/.claude/settings.json` to make them available in every project | ||||
| 721 | +* **Plugins**: package and distribute configuration as a [plugin](https://code.claude.com/docs/en/plugins/overview.md) that teams can install | ||||
| 722 | +* **Launch from the config directory**: run Claude Code from the directory containing the `.claude/` configuration you want | ||||
| 723 | + | ||||
| 724 | +## How permissions interact with sandboxing | ||||
| 725 | + | ||||
| 726 | +Permissions and [sandboxing](https://code.claude.com/docs/en/sandboxing.md) are complementary security layers: | ||||
| 727 | + | ||||
| 728 | +* **Permissions** control which tools Claude Code can use and which files or domains it can access. They apply to Bash, Read, Edit, WebFetch, MCP, and every other tool, except that a deny or ask rule can't block [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) while any other tool remains. | ||||
| 729 | +* **Sandboxing** provides OS-level enforcement that restricts shell commands' filesystem and network access. It applies to Bash, PowerShell, and [Monitor](https://code.claude.com/docs/en/tools-reference.md#monitor-tool) tool commands and their child processes. | ||||
| 730 | + | ||||
| 731 | +Use both for defense-in-depth, since sandbox restrictions still apply even if a prompt injection bypasses Claude's decision-making. Paths and domains from both sandbox settings and permission rules are [merged into the final sandbox configuration](https://code.claude.com/docs/en/sandboxing.md#permission-rules). | ||||
| 732 | + | ||||
| 733 | +When you enable sandboxing and leave `autoAllowBashIfSandboxed` at its default of `true`, sandboxed Bash commands run without prompting even if your permissions include a bare `Bash` ask rule, or the [equivalent `Bash(*)` form](#match-all-uses-of-a-tool): the sandbox boundary substitutes for that whole-tool prompt. | ||||
| 734 | + | ||||
| 735 | +In [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode), Claude Code skips this substitution. Without an ask rule, the [built-in read-only commands](#read-only-commands) still run without prompting, and any other shell command goes through the regular permission flow while you are still planning; see [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) for how Claude Code gates commands there. With a bare `Bash` ask rule, every Bash command prompts, including sandboxed read-only commands, the same as outside sandboxing. | ||||
| 736 | + | ||||
| 737 | +These checks still apply: | ||||
| 738 | + | ||||
| 739 | +* Content-scoped ask rules like `Bash(git push *)` still force a prompt | ||||
| 740 | +* Other sandboxed commands can go through the regular permission flow too, as [Auto-allow mode](https://code.claude.com/docs/en/sandboxing.md#auto-allow-mode) describes | ||||
| 741 | + | ||||
| 742 | +Commands that won't run sandboxed, such as excluded commands, respect the bare `Bash` ask rule as usual. See [sandbox modes](https://code.claude.com/docs/en/sandboxing.md#sandbox-modes) to change this behavior. | ||||
| 743 | + | ||||
| 744 | +## Managed settings | ||||
| 745 | + | ||||
| 746 | +For organizations that need centralized control, administrators deploy managed settings that user and project settings can't override, apart from a few [security-sensitive keys](https://code.claude.com/docs/en/settings.md#exceptions-to-managed-settings-precedence). [Deploy managed settings](https://code.claude.com/docs/en/managed-settings.md) covers the delivery mechanisms, precedence within the managed tier, and the [keys that only managed settings can set](https://code.claude.com/docs/en/managed-settings.md#managed-only-settings). | ||||
| 747 | + | ||||
| 748 | +One of those keys, [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedpermissionrulesonly), makes managed settings the only settings source of permission rules. Its entry lists every source Claude Code then ignores. | ||||
| 749 | + | ||||
| 750 | +`disableBypassPermissionsMode` is typically placed in managed settings to enforce organizational policy, but it works from any scope. A user can set it in their own settings to lock themselves out of bypass mode. | ||||
| 751 | + | ||||
| 752 | +## Settings precedence | ||||
| 753 | + | ||||
| 754 | +Permission rules follow the same [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) as all other Claude Code settings, with managed settings highest: no other level, including command line arguments, can override a managed permission rule. | ||||
| 755 | + | ||||
| 756 | +If a tool is denied at any level, no other level can allow it. For example, a managed settings deny can't be overridden by `--allowedTools`, and `--disallowedTools` can add restrictions beyond what managed settings define. | ||||
| 757 | + | ||||
| 758 | +The same holds across settings scopes: if user settings allow a permission and project settings deny it, the deny rule blocks it. The reverse is also true: a user-level deny blocks a project-level allow, because deny rules from any scope are evaluated before allow rules. | ||||
| 759 | + | ||||
| 760 | +This precedence is between settings files and command line arguments. For whether a deny rule holds over a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you install, see [Extend permissions with hooks](#extend-permissions-with-hooks). | ||||
| 761 | + | ||||
| 762 | +Embedding hosts can supply additional managed policy via the SDK `managedSettings` option, including permission allow rules unless the admin sets the `allowManaged*Only` locks; [Deliver policy to Claude Desktop sessions](https://code.claude.com/docs/en/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions) covers when embedder policy applies at all. | ||||
| 763 | + | ||||
| 764 | +## Project allow rules and workspace trust | ||||
| 765 | + | ||||
| 766 | +`permissions.allow` rules and `permissions.additionalDirectories` entries in a project's `.claude/settings.json` grant capability, so Claude Code applies them only after you accept the [workspace trust dialog](https://code.claude.com/docs/en/security.md#additional-safeguards) for that folder. The dialog lists the rules and directories the folder would grant so you can review them first. `deny` and `ask` rules aren't affected, since they only restrict. | ||||
| 767 | + | ||||
| 768 | +Claude Code keys and stores the trust you accept according to where you start it: | ||||
| 769 | + | ||||
| 770 | +* In a repository, Claude Code keys the trust on the git repository root, so the trust covers the whole repository apart from any git repository nested inside it, such as a submodule. In a [worktree](https://code.claude.com/docs/en/worktrees.md), it uses the main checkout's root, as it does for [saved rules](#permission-system). | ||||
| 771 | +* Outside a repository, Claude Code keys the trust on the directory you started it from, and the trust covers any subdirectory of that directory apart from a git repository nested inside it, such as a clone. Each covered subdirectory then counts as a folder whose parent you trusted. | ||||
| 772 | +* When you start in your home directory, Claude Code holds the trust for the current session only and doesn't write it to disk; see the [additional safeguards](https://code.claude.com/docs/en/security.md#additional-safeguards) note. | ||||
| 773 | + | ||||
| 774 | +Claude Code shows the trust dialog in interactive sessions only. A `claude -p` run or an SDK session never shows it, and trusting a parent folder doesn't count for these rules, so [What runs before you trust a folder](#what-runs-before-you-trust-a-folder) says which repository content Claude Code still uses in each of those two situations. | ||||
| 775 | + | ||||
| 776 | +Before it starts or restarts a [background session](https://code.claude.com/docs/en/agent-view.md), Claude Code also checks workspace trust for the directory the session runs in. If you run `claude --bg` from a terminal in a directory you haven't trusted, the trust dialog appears first and the session starts once you accept it. Where no dialog can appear, such as in a script, the command exits with a [`Workspace not trusted`](https://code.claude.com/docs/en/errors#workspace-not-trusted-when-dispatching-a-background-session) error instead. | ||||
| 777 | + | ||||
| 778 | +### When your local settings file needs trust | ||||
| 779 | + | ||||
| 780 | +`.claude/settings.local.json` is normally your own file, so Claude Code applies its allow rules and additional directories without the trust step. When the file is tracked in git, or `.claude` is a symlink, Claude Code treats it as repository-supplied instead and holds its rules until you trust the folder. | ||||
| 781 | + | ||||
| 782 | +Claude Code runs git to tell the two apart, and it runs git only once you've trusted the folder: you accepted the trust dialog for it or for a parent directory whose trust extends to it, or you're in a `-p` or SDK session, which counts as accepted. Until then, where you started Claude Code decides what happens to the file's rules: | ||||
| 783 | + | ||||
| 784 | +* **In your configuration home:** Claude Code applies that folder's `.claude/settings.local.json` right away without running git. Your configuration home is your home directory, or a directory whose `.claude` subdirectory you've set as [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars#variables). If that `CLAUDE_CONFIG_DIR` directory sits inside a git repository and Claude Code [keeps your local settings at the repository root](https://code.claude.com/docs/en/settings.md#where-claude-code-looks-for-each-file) instead, it holds the rules like anywhere else. | ||||
| 785 | +* **Anywhere else:** Claude Code holds the file's rules like project settings. Once the check has run, Claude Code applies the rules of an untracked file, or of a file in a directory outside any git repository, even though you haven't trusted that exact folder. | ||||
| 786 | + | ||||
| 787 | +> [!NOTE] | ||||
| 788 | +> | ||||
| 789 | +> The configuration-home exception skips only the trust step. `~/.claude/settings.local.json` is still [local scope](https://code.claude.com/docs/en/settings.md#compare-the-scope-of-each-settings-file), so Claude Code reads it only in sessions you start in your home directory itself, not in every project. To apply permission rules across all your projects, add them to your user settings instead: `~/.claude/settings.json`, or `$CLAUDE_CONFIG_DIR/settings.json` when `CLAUDE_CONFIG_DIR` is set. | ||||
| 790 | + | ||||
| 791 | +### What runs before you trust a folder | ||||
| 792 | + | ||||
| 793 | +Each row is one kind of content a repository can supply. The columns are the two situations in which you haven't trusted the folder itself: you trusted only a parent folder, or you ran `claude -p` or the SDK there, which never shows the trust dialog. The parent-folder column doesn't apply inside a [nested repository](#project-allow-rules-and-workspace-trust): in an interactive session Claude Code shows the trust dialog for it, and a `claude -p` or SDK run there follows the `claude -p` column. | ||||
| 794 | + | ||||
| 795 | +| What the repository supplies | You trusted only a parent folder | `claude -p` or the SDK, folder never trusted | | ||||
| 796 | +| :- | :- | :- | | ||||
| 797 | +| [Hooks](https://code.claude.com/docs/en/hooks.md) in settings files, the [`env`](https://code.claude.com/docs/en/settings-reference#env) block and helper commands such as [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper), and a project skill's [hooks](https://code.claude.com/docs/en/hooks.md#hooks-in-skills-and-agents) and [`allowed-tools`](https://code.claude.com/docs/en/skills#pre-approve-tools-for-a-skill) | Used | Used. Workspace trust never gates a skill's `allowed-tools` in any session | | ||||
| 798 | +| `permissions.allow` rules and `additionalDirectories` in `.claude/settings.json` | Not used until you accept the trust dialog, which appears again listing them | Not used. Claude Code prints a [`this workspace has not been trusted`](https://code.claude.com/docs/en/errors#workspace-has-not-been-trusted) warning to stderr | | ||||
| 799 | +| Frontmatter hooks in a project [subagent](https://code.claude.com/docs/en/sub-agents.md#hooks-in-subagent-frontmatter), a project [`@skills-dir` plugin](https://code.claude.com/docs/en/plugins/loading#plugins-shared-through-a-repository), and [`extraKnownMarketplaces`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces) entries from the repository or an `--add-dir` directory | Not used, and no dialog is offered | Not used | | ||||
| 800 | +| Inline [`mcpServers`](https://code.claude.com/docs/en/sub-agents#scope-mcp-servers-to-a-subagent) in the frontmatter of a subagent from the repository or an `--add-dir` directory | Not used, and no dialog is offered | Not used | | ||||
| 801 | +| Servers in `.mcp.json`, including ones the repository [approves in its own settings](https://code.claude.com/docs/en/mcp.md#project-server-approvals-and-workspace-trust) | Claude Code asks you before connecting them. The repository's own approvals don't count | Connected without asking, approved or not. The SDK loads them only when `settingSources` includes project settings. `claude mcp list` in the same folder still reports such a server as pending | | ||||
| 802 | +| A [`headersHelper`](https://code.claude.com/docs/en/mcp#trust-a-folder-before-its-headershelper-runs) on a server in `.mcp.json` | Not run until you accept the trust dialog, which appears again naming where the helper is declared. Claude Code connects the server with its static `headers` alone until then | Not run. Claude Code connects the server with its static `headers` alone and prints a [`headersHelper not run`](https://code.claude.com/docs/en/errors#headershelper-not-run) line per server to stderr | | ||||
| 803 | + | ||||
| 804 | +For the rows that need this exact folder trusted, trust it by hand: set `projects["<path>"].hasTrustDialogAccepted` to `true` in `~/.claude.json`, where `<path>` is the repository root, or the folder itself outside a repository. Claude Code prints the exact key in the debug log line for a skipped subagent hook or inline MCP server, in the stderr warning for skipped allow rules, and in the `headersHelper not run` line for a skipped helper. | ||||
| 805 | + | ||||
| 806 | +Before you run `claude -p` in a repository you didn't write, decide what it may run on your machine: | ||||
| 807 | + | ||||
| 808 | +* Pass `--setting-sources user`, or set the SDK's `settingSources` without project settings, so Claude Code reads neither the project's settings files nor its `.mcp.json` | ||||
| 809 | +* Start with [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode) so Claude Code reads no hooks, skills, custom commands, subagents, plugins, or `.mcp.json` servers from the project. The project's `env` block and helpers such as `awsAuthRefresh` in its settings files still apply, and Claude Code reads `apiKeyHelper` only from `--settings` | ||||
| 810 | +* Pass `--settings '{"disableAllHooks": true}'` to [turn hooks off](https://code.claude.com/docs/en/hooks.md#disable-or-remove-hooks) for that run. Setting it in your user settings alone isn't enough, because the repository's project settings take precedence over yours and can set it back to `false` | ||||
| 811 | +* Add a [`disabledMcpjsonServers`](https://code.claude.com/docs/en/settings-reference#disabledmcpjsonservers) entry to reject a `.mcp.json` server by name in every session type | ||||
| 812 | + | ||||
| 813 | +## Example configurations | ||||
| 814 | + | ||||
| 815 | +This [repository](https://github.com/anthropics/claude-code/tree/main/examples/settings) includes starter settings configurations for common deployment scenarios. Use these as starting points and adjust them to fit your needs. | ||||
| 816 | + | ||||
| 817 | +## See also | ||||
| 818 | + | ||||
| 819 | +* [All settings](https://code.claude.com/docs/en/settings-reference.md#permission-settings): every settings key, including the permission keys | ||||
| 820 | +* [Configure auto mode](https://code.claude.com/docs/en/auto-mode-config.md): tell the auto mode classifier which infrastructure your organization trusts | ||||
| 821 | +* [Sandboxing](https://code.claude.com/docs/en/sandboxing.md): OS-level filesystem and network isolation for Bash commands | ||||
| 822 | +* [Authentication](https://code.claude.com/docs/en/authentication.md): set up user access to Claude Code | ||||
| 823 | +* [Security](https://code.claude.com/docs/en/security.md): security safeguards and best practices | ||||
| 824 | +* [Hooks](https://code.claude.com/docs/en/hooks-guide.md): automate workflows and extend permission evaluation | ||||
added
docs/claude-code-docs/retrieved_utc.txt
+1 −0
@@ -0,0 +1 @@ | |||||
| 1 | +2026-10-30T03:01:55Z | ||||
added
protocol/WP29_FULL_MANDATE.md
+962 −0
@@ -0,0 +1,962 @@ | |||||
| 1 | +# CLAUDE.md — UQO Working Paper 29 | ||||
| 2 | + | ||||
| 3 | +Protocol-Guided Autonomous Research with Claude Code | ||||
| 4 | + | ||||
| 5 | +A Reproducible Experimental Study of Scientific Execution, Verification, and Recovery | ||||
| 6 | + | ||||
| 7 | +Principal researcher: Simon-Pierre Boucher, Université du Québec en Outaouais. | ||||
| 8 | +Project identity: UQO Working Paper No. 29 / WP29; follow the series' verified numbering conventions. | ||||
| 9 | +Language: English throughout the paper, code documentation, captions, tables, research logs and appendices. | ||||
| 10 | +Mandate prepared: 29 October 2026. Refresh technical documentation and literature at execution time. | ||||
| 11 | +Deliverable: a genuine research article supported by an implemented method, live Claude Code experiments, auditable evidence, authentic screenshots, statistical analysis and a reproducibility package. | ||||
| 12 | + | ||||
| 13 | +This file is the complete research execution mandate. It is intentionally more detailed than a routine repository instruction file. Read it in full in manageable sections, build an indexed phase plan, and preserve an immutable copy. If the installed client's context limits make a modular layout necessary, preserve this complete mandate under protocol/WP29_FULL_MANDATE.md, use a concise root CLAUDE.md, and explicitly load and record the sections needed for each phase. Do not discard requirements while reorganizing them. | ||||
| 14 | + | ||||
| 15 | +> Provenance note (added by the executor, 2026-10-29): this file is a verbatim preservation of the mandate pasted by the principal researcher into the Claude Code session that started WP29 on 2026-10-29 (local time, Gatineau). Two obvious paste artefacts in §2.1 ("mon WP18–'WP26", "byte-identical l '' L to") are preserved as received. SHA-256 of this file is recorded in `protocol/amendments.csv` at freeze time. | ||||
| 16 | + | ||||
| 17 | +## 0. Execute the research, not merely a description of the research | ||||
| 18 | + | ||||
| 19 | +You are the research executor for WP29. Your job is to implement, run, measure, challenge and document a method for autonomous scientific research using Claude Code. | ||||
| 20 | + | ||||
| 21 | +The central requirement is real experimentation with Claude Code as an experimental subject. Launch genuine, authorized Claude Code sessions on scientific tasks; collect their actual outputs; evaluate their artifacts; capture the real execution interface or genuine evidence dashboards; measure outcomes; and write the paper from those observations. A plausible account of what an agent would do is not an experiment. Mock providers and replayed responses may test infrastructure but must never be presented as fresh live-Claude observations. | ||||
| 22 | + | ||||
| 23 | +Complete phases in dependency order and continue autonomously through feasible work. Do not stop after a plan, a repository scaffold, a literature summary, a demonstration screenshot or a draft introduction. Make normal reversible technical decisions within the authorized scope, document them, and proceed. Ask only when an indispensable external input, access right, resource limit or scope-changing decision is genuinely missing. Existing authorization remains valid; do not repeatedly request it. | ||||
| 24 | + | ||||
| 25 | +Scientific integrity overrides the desired direction of results: | ||||
| 26 | + | ||||
| 27 | +- Never invent experiments, participants, prompts, screenshots, model identifiers, outputs, tokens, prices, elapsed times, citations, effect sizes or significance. | ||||
| 28 | +- Do not assume the proposed method outperforms simpler instructions. A credible null or negative result is acceptable. | ||||
| 29 | +- Do not describe the paper as fully autonomous without measuring human preparation, intervention and review. | ||||
| 30 | +- Do not conflate a role instruction with an independently running agent, or a different session with independent scientific judgment. | ||||
| 31 | +- Do not treat a successful process exit, a compiled PDF or an agent's declaration of success as scientific validation. | ||||
| 32 | +- Do not claim experiments were performed on the researcher's infrastructure unless the actual permitted machines and runs were recorded. | ||||
| 33 | +- Do not submit, publish, contact reviewers or make external commitments as an implicit part of preparing the manuscript. | ||||
| 34 | + | ||||
| 35 | +### 0.1 WP29 identity and collision handling | ||||
| 36 | + | ||||
| 37 | +Inspect the existing UQO research index and working directory first. The latest user instruction assigns this autonomous-research-method paper to WP29. An earlier idea may also have used WP29. Do not overwrite or delete unrelated work and do not silently renumber this project. If a collision exists, preserve the prior material, document the conflict and create an isolated branch or working directory for the currently requested WP29. Resolve the index transparently before final packaging. | ||||
| 38 | + | ||||
| 39 | +### 0.2 Authorship and disclosure | ||||
| 40 | + | ||||
| 41 | +Use Simon-Pierre Boucher as the named researcher. Verify the affiliation format from current UQO working-paper sources. Do not invent coauthors, grants, funding, approvals, institutional endorsements or human reviewers. Do not automatically apply funding language from another project. | ||||
| 42 | + | ||||
| 43 | +Include a substantive AI-use statement specifying who prepared the mandate, which agent designed the harness, which agents executed tasks, which tools evaluated outputs, and what human review actually occurred. Treat model identities as provenance rather than accountable human authorship. Check the chosen venue's current disclosure requirements before preparing a submission version. | ||||
| 44 | + | ||||
| 45 | +## 1. Scientific question and intended contribution | ||||
| 46 | + | ||||
| 47 | +### 1.1 Main research question | ||||
| 48 | + | ||||
| 49 | +> Under controlled information, tool access and resource conditions, does an explicit research protocol, combined with executable verification and persistent evidence records, improve Claude Code's ability to complete scientifically valid research tasks autonomously, and at what cost in compute, time and human effort? | ||||
| 50 | + | ||||
| 51 | +### 1.2 Secondary questions | ||||
| 52 | + | ||||
| 53 | +1. Which benefits come from structured instructions, executable gates, durable state or separate review? | ||||
| 54 | +2. Does the method reduce unsupported claims, data leakage, invalid statistical inference, incomplete replication and false declarations of completion? | ||||
| 55 | +3. Can execution resume after interruption without losing provenance, duplicating expensive jobs or silently changing the protocol? | ||||
| 56 | +4. When do stronger controls reduce throughput or cause unnecessary blocking? | ||||
| 57 | +5. Does observed improvement survive task, model-version, budget and domain variation? | ||||
| 58 | +6. How much human work is shifted into specification, evaluator construction and final review? | ||||
| 59 | +7. Which elements transfer from short scientific tasks to bounded end-to-end research projects? | ||||
| 60 | +8. What can screenshots and traces verify, and what requires independent artifact or scientific evaluation? | ||||
| 61 | + | ||||
| 62 | +### 1.3 Candidate contribution | ||||
| 63 | + | ||||
| 64 | +Develop and evaluate a method called Protocol-Guided Autonomous Research, abbreviated PGAR as a working label only. Check prior usage before treating the label as distinctive. | ||||
| 65 | + | ||||
| 66 | +The candidate contribution has four components: | ||||
| 67 | + | ||||
| 68 | +- A scientific delegation contract: objectives, estimands, evidence requirements, permitted adaptation and stopping rules. | ||||
| 69 | +- A reference execution system: phase scheduling, durable state, provenance, bounded recovery and executable controls. | ||||
| 70 | +- An experimental evaluation: randomized or carefully blocked comparisons using actual Claude Code executions. | ||||
| 71 | +- An evidence package: frozen task definitions, traces, results, authentic visual records, evaluation code and a reproducible paper build. | ||||
| 72 | + | ||||
| 73 | +These are proposed contributions, not established achievements. Determine the closest prior work before claiming novelty. Be willing to position the paper as a careful systems-and-methodology evaluation rather than a new general intelligence architecture. | ||||
| 74 | + | ||||
| 75 | +### 1.4 Working titles | ||||
| 76 | + | ||||
| 77 | +Primary working title: | ||||
| 78 | + | ||||
| 79 | +Protocol-Guided Autonomous Research with Claude Code: Scientific Verification, Reproducibility, and the Cost of Delegation | ||||
| 80 | + | ||||
| 81 | +Alternative, if the experiment supports the emphasis: | ||||
| 82 | + | ||||
| 83 | +From Research Instructions to Verified Scientific Execution: A Controlled Study of Claude Code | ||||
| 84 | + | ||||
| 85 | +Choose the final title from the demonstrated scope. Avoid titles implying universal autonomy, guaranteed discovery or superiority that the study has not established. | ||||
| 86 | + | ||||
| 87 | +## 2. Source material and corpus audit | ||||
| 88 | + | ||||
| 89 | +### 2.1 Available methodological starting point | ||||
| 90 | + | ||||
| 91 | +Locate these existing artifacts if supplied in the research environment: | ||||
| 92 | + | ||||
| 93 | +- Methode_recherche_autonome_CLAUDE.pdf: methodological guide derived from the researcher's mandates. | ||||
| 94 | +- Kit_recherche_autonome_CLAUDE.zip: reusable protocol and registry templates. | ||||
| 95 | +- CLAUDE_WP_UQO_2026-10-29.zip: the collected source mandates. | ||||
| 96 | + | ||||
| 97 | +These files are starting specifications, not a dataset of completed autonomous experiments. Their presence does not establish that any previous working paper was executed without human assistance. | ||||
| 98 | + | ||||
| 99 | +If the files are not mounted, retrieve the accessible primary mandates using actual endpoints and preserve content hashes: | ||||
| 100 | + | ||||
| 101 | +- WP15: https://git.spboucher.ai/raw/wp15_uqo/main/docs/CLAUDE.md | ||||
| 102 | +- WP18–WP26: https://git.spboucher.ai/raw/wp{N}_uqo/main/CLAUDE.md | ||||
| 103 | +- WP28: https://git.spboucher.ai/raw/wp28_uqo/main/CLAUDE.md | ||||
| 104 | +- WP27 supplementary brief: https://git.spboucher.ai/raw/wp27_uqo/main/docs/DESIGN-BRIEF.md | ||||
| 105 | + | ||||
| 106 | +The previously collected corpus contained eleven distinct files named CLAUDE.md: WP15, mon WP18–'WP26 and WP28. WP15's PROMPT_INITIAL_CLAUDE.md was byte-identical l '' L to its CLAUDE.md in that snapshot; check rather than count it twice. WP27's design brief is not an additional CLAUDE.md. Current remote contents may differ from the collected snapshot. | ||||
| 107 | + | ||||
| 108 | +### 2.2 Descriptive analysis of the mandates | ||||
| 109 | + | ||||
| 110 | +Create a reproducible content-coding protocol. For each document record: | ||||
| 111 | + | ||||
| 112 | +- source URL, retrieval time, content hash and available revision metadata; | ||||
| 113 | +- research domain and type; | ||||
| 114 | +- explicit question, estimand, assumptions and falsification conditions; | ||||
| 115 | +- literature and novelty requirements; | ||||
| 116 | +- data-access and temporal-information controls; | ||||
| 117 | +- baseline requirements; | ||||
| 118 | +- phases, dependencies, gates, stopping rules and recovery instructions; | ||||
| 119 | +- artifact requirements, provenance, review and disclosure; | ||||
| 120 | +- instruction length and contradictory or non-operational requirements; | ||||
| 121 | +- statements added during implementation when explicitly identified. | ||||
| 122 | + | ||||
| 123 | +Separate verbatim observations from analyst interpretation. State whether coding was automated, manually reviewed or both. If no human second coder exists, do not invent intercoder reliability. Use this small, researcher-selected corpus to motivate design patterns, not to estimate the prevalence of practices across all research. | ||||
| 124 | + | ||||
| 125 | +Do not treat existing source mandates as hidden evaluation tasks if the executor has already read their solutions or outputs. Derive new, clearly documented task instances for experimental evaluation and separate development from final tasks. | ||||
| 126 | + | ||||
| 127 | +## 3. Literature and technical reconnaissance | ||||
| 128 | + | ||||
| 129 | +### 3.1 Literature streams | ||||
| 130 | + | ||||
| 131 | +Conduct and record a current primary-source review covering: | ||||
| 132 | + | ||||
| 133 | +1. Autonomous scientific discovery and agentic research systems. | ||||
| 134 | +2. Language agents for data analysis and scientific programming. | ||||
| 135 | +3. Scientific-workflow systems, provenance and computational reproducibility. | ||||
| 136 | +4. Preregistration, registered reports and specification discipline. | ||||
| 137 | +5. Agent evaluation, benchmark contamination and evaluator validity. | ||||
| 138 | +6. Human–AI delegation, automation bias and intervention measurement. | ||||
| 139 | +7. Durable execution, failure recovery, observability and resource accounting. | ||||
| 140 | +8. Evidence-grounded generation and verification of scientific claims. | ||||
| 141 | + | ||||
| 142 | +Verified starting identifiers, to read in full and check for subsequent versions: | ||||
| 143 | + | ||||
| 144 | +- The AI Scientist-v2: https://arxiv.org/abs/2504.08066 | ||||
| 145 | +- Agent Laboratory: https://arxiv.org/abs/2501.04227 | ||||
| 146 | +- ScienceAgentBench: https://arxiv.org/abs/2410.05080 | ||||
| 147 | + | ||||
| 148 | +Expand from these sources and their references. Do not copy reported headline results into the manuscript without checking design, units, uncertainty and comparison conditions. Do not label a preprint as peer-reviewed without verification. | ||||
| 149 | + | ||||
| 150 | +Create research/literature_matrix.csv, research/novelty_matrix.csv, research/source_notes.md and verified BibTeX. Compare PGAR to the closest systems on inputs, workflow, verification, human involvement, task scope, resources and evaluated outcomes. Explain which ideas are established and where the present implementation or evidence adds something. | ||||
| 151 | + | ||||
| 152 | +### 3.2 Verify the installed Claude Code environment | ||||
| 153 | + | ||||
| 154 | +Inspect current official documentation and the actual installed client: | ||||
| 155 | + | ||||
| 156 | +- https://code.claude.com/docs/en/memory | ||||
| 157 | +- https://code.claude.com/docs/en/headless | ||||
| 158 | +- https://code.claude.com/docs/en/cli-reference | ||||
| 159 | +- https://code.claude.com/docs/en/hooks | ||||
| 160 | +- https://code.claude.com/docs/en/permissions | ||||
| 161 | + | ||||
| 162 | +Record retrieval dates and relevant versions. Run harmless capability probes such as claude --version and claude --help, and inspect the installed authentication/status mechanism without printing secrets. | ||||
| 163 | + | ||||
| 164 | +The documentation consulted when preparing this mandate describes non-interactive execution through claude -p, structured output and session resumption. It also distinguishes instruction loading from enforced permissions and notes that bare mode skips automatic CLAUDE.md discovery. Verify these behaviors on the installed version before constructing experimental arms. Do not assume that passing a filename or mentioning it in prose caused the intended instructions to load. | ||||
| 165 | + | ||||
| 166 | +Use only supported flags and authentication flows. Preserve the exact command, settings and effective loaded context for every run. Do not assume a temperature parameter, random-seed flag, pricing model or model identifier exists. Unsupported controls must be reported as unavailable, not silently simulated. | ||||
| 167 | + | ||||
| 168 | +## 4. Formalize the research method | ||||
| 169 | + | ||||
| 170 | +### 4.1 Research contract | ||||
| 171 | + | ||||
| 172 | +Represent a protocol as: | ||||
| 173 | + | ||||
| 174 | +P = (Q, Θ, D, A, G, V, B, R, L), | ||||
| 175 | + | ||||
| 176 | +where: | ||||
| 177 | + | ||||
| 178 | +- Q: scientific questions and scope; | ||||
| 179 | +- Θ: estimands, hypotheses, assumptions and admissible interpretations; | ||||
| 180 | +- D: data, documents, versions and information-availability restrictions; | ||||
| 181 | +- A: authorized actions and tools; | ||||
| 182 | +- G: phase dependency graph; | ||||
| 183 | +- V: verification criteria and evaluator definitions; | ||||
| 184 | +- B: resource budgets and stopping constraints; | ||||
| 185 | +- R: recovery, amendment and escalation rules; | ||||
| 186 | +- L: required evidence and provenance records. | ||||
| 187 | + | ||||
| 188 | +Use this notation only if it clarifies actual implementation. Explain how every component is serialized and used. Do not present decorative notation as a theorem or as evidence of rigor. | ||||
| 189 | + | ||||
| 190 | +### 4.2 State and transitions | ||||
| 191 | + | ||||
| 192 | +Define states pending, running, passed, failed, blocked, stale, and skipped_optional. A phase becomes eligible only when its required dependencies are satisfied. An artifact's validity is conditional on the input, code, configuration and criterion versions used to produce and evaluate it. | ||||
| 193 | + | ||||
| 194 | +Specify invariants that the harness can actually enforce: | ||||
| 195 | + | ||||
| 196 | +1. A required phase cannot be passed without its required check receipts. | ||||
| 197 | +2. A changed upstream artifact invalidates affected downstream results. | ||||
| 198 | +3. A run cannot consume more than the externally enforced resource envelope without being stopped or explicitly amended. | ||||
| 199 | +4. A claim cannot be marked verified without a corresponding evidence record and appropriate evaluator outcome. | ||||
| 200 | +5. An optional skipped phase cannot be used to support a claim that requires its results. | ||||
| 201 | + | ||||
| 202 | +These are workflow invariants, not guarantees that every scientific conclusion is true. State the limits of the checkers. If presenting propositions about state consistency, give precise assumptions and a short proof or exhaustive property tests as appropriate; never imply those properties establish scientific correctness. | ||||
| 203 | + | ||||
| 204 | +### 4.3 Observable autonomy | ||||
| 205 | + | ||||
| 206 | +Distinguish: | ||||
| 207 | + | ||||
| 208 | +- workflow autonomy: phases executed without operational human guidance; | ||||
| 209 | +- scientific completion: artifacts satisfy the independent task rubric; | ||||
| 210 | +- intervention-free verified completion: both conditions hold; | ||||
| 211 | +- autonomous execution with incorrect output: no intervention, but scientific failure; | ||||
| 212 | +- correct assisted completion: success after substantive human intervention. | ||||
| 213 | + | ||||
| 214 | +The method must preserve these distinctions in its database, plots, tables and claims. | ||||
| 215 | + | ||||
| 216 | +## 5. Build a reference implementation | ||||
| 217 | + | ||||
| 218 | +### 5.1 Components | ||||
| 219 | + | ||||
| 220 | +Implement a real, runnable system with: | ||||
| 221 | + | ||||
| 222 | +- a task registry and immutable task bundles; | ||||
| 223 | +- treatment-specific instruction assembly; | ||||
| 224 | +- isolated executor workspaces; | ||||
| 225 | +- a bounded process/session launcher; | ||||
| 226 | +- an event collector and durable state store; | ||||
| 227 | +- deterministic verification adapters; | ||||
| 228 | +- a separate scientific-evaluation layer; | ||||
| 229 | +- a resource and cost accountant; | ||||
| 230 | +- failure-injection and recovery machinery; | ||||
| 231 | +- an evidence browser and screenshot capture mechanism; | ||||
| 232 | +- statistical analysis and manuscript-generation pipelines. | ||||
| 233 | + | ||||
| 234 | +Prefer a small auditable Python implementation using standard libraries and justified dependencies. SQLite is adequate for structured state when concurrency and transactions are handled correctly. Export analysis-ready CSV/Parquet files. Avoid building a large web platform before the core experiment runs. | ||||
| 235 | + | ||||
| 236 | +### 5.2 Separation of roles and trust | ||||
| 237 | + | ||||
| 238 | +Distinguish the builder, executor, runtime verifier, final evaluator, reviewer and reporting pipeline. | ||||
| 239 | + | ||||
| 240 | +The builder may be Claude Code developing this study. The executors must be fresh actual Claude Code sessions under the assigned treatment. The final evaluator must not rely exclusively on the executor's self-assessment. | ||||
| 241 | + | ||||
| 242 | +Keep hidden labels, expected results, held-out instances, frozen rubrics and authoritative evaluator logs inaccessible to executors through real filesystem/process/access isolation. A prompt saying "do not read the answers" is insufficient. A Git worktree with read access to its parent or sibling directories is not a security boundary. | ||||
| 243 | + | ||||
| 244 | +Use supported containers, separate OS identities, mounted read-only bundles or another verifiable isolation mechanism. Preserve legitimate authentication without exposing credentials. Test the boundary using harmless probes. Do not weaken permission systems or defeat nested-session protections to make an experiment run. If the supported client disallows nested invocation, use an authorized external supervisor or documented session launch mechanism, and record that architecture. | ||||
| 245 | + | ||||
| 246 | +The builder's involvement in task design is a limitation. Fresh executor contexts do not make the whole benchmark externally independent. Prefer reference answers from analytical identities, independently implemented deterministic solutions, external benchmarks or an evaluator-controlled task generator. Document who could access answers at each stage. | ||||
| 247 | + | ||||
| 248 | +### 5.3 Instruction and memory contamination | ||||
| 249 | + | ||||
| 250 | +Experimental workspaces must not inherit this WP29 mandate or the full PGAR treatment when assigned to a weaker arm. Audit parent CLAUDE.md files, user-level instructions, auto memory, rules, plugins, hooks, MCP servers, cached state and conversation history. | ||||
| 251 | + | ||||
| 252 | +Apply a verified, supported isolation configuration consistently across arms. If bare mode is used, explicitly supply the intended instructions and needed capabilities for every arm and document any departures from ordinary interactive usage. Do not accidentally compare different instruction loaders, tool inventories or authentication behaviors as if only protocol structure differed. | ||||
| 253 | + | ||||
| 254 | +Record both intended and effective configuration. Test isolation with innocuous sentinel instructions before final experiments, then remove sentinels from the scientific tasks. Failed isolation invalidates the affected comparison and requires a documented rerun policy. | ||||
| 255 | + | ||||
| 256 | +### 5.4 Durable execution | ||||
| 257 | + | ||||
| 258 | +Persist state atomically; log jobs before submission; capture process/session/job IDs; reconcile external jobs before resuming. Make retry policy idempotent where possible. Separate transient service retries from additional scientific reasoning attempts and charge both to the resource accounting. | ||||
| 259 | + | ||||
| 260 | +The controller uses bounded work units and explicit termination conditions. It must not recursively spawn unbounded copies of itself. Apply an allowlisted executor entry point and a configured maximum process/session depth. Experimental workers solve assigned tasks; they do not launch another WP29 study. | ||||
| 261 | + | ||||
| 262 | +## 6. A genuine self-experiment without circular validation | ||||
| 263 | + | ||||
| 264 | +"Claude experimenting with itself" means that Claude Code helps implement a study in which actual Claude Code instances are subjects under controlled conditions. It does not mean introspection, self-reported competence or a dialogue in which one role declares another role successful. | ||||
| 265 | + | ||||
| 266 | +For each observation preserve: | ||||
| 267 | + | ||||
| 268 | +1. Frozen task, inputs and treatment assignment. | ||||
| 269 | +2. Fresh execution identity and effective environment. | ||||
| 270 | +3. Actual invocation, live events and tool outputs. | ||||
| 271 | +4. Submitted artifacts and terminal status. | ||||
| 272 | +5. Independent evaluation receipts. | ||||
| 273 | +6. Resource usage and intervention history. | ||||
| 274 | +7. Screenshots or other visual evidence tied to the run. | ||||
| 275 | + | ||||
| 276 | +The principal experimental observations must use real Claude Code inference. A simulator, a provider mock, copied responses, or a non-Claude model behind a compatibility endpoint cannot be counted as a live Claude Code observation. Such runs may appear in a separate engineering validation section with accurate labels. | ||||
| 277 | + | ||||
| 278 | +Do not request or invent hidden chain-of-thought. Analyze observable actions, visible messages, tool calls, files, explicit decisions and errors. Describe this as behavioral and artifact evidence, not privileged access to the model's internal reasoning. | ||||
| 279 | + | ||||
| 280 | +If live execution is genuinely unavailable, complete infrastructure and clearly labeled mock tests, but report the empirical study as blocked. Do not submit a fictional results paper to satisfy the mandate. The requested completion target still requires live experiments once the missing access is supplied. | ||||
| 281 | + | ||||
| 282 | +## 7. Research hypotheses and primary endpoints | ||||
| 283 | + | ||||
| 284 | +Formulate and freeze hypotheses before confirmatory runs. Suggested hypotheses: | ||||
| 285 | + | ||||
| 286 | +- H1: a structured protocol improves intervention-free, science-verified completion relative to an information-matched open instruction. | ||||
| 287 | +- H2: executable gates reduce critical integrity failures relative to a protocol without mandatory runtime gates. | ||||
| 288 | +- H3: separate review improves claim validity, with measurable additional cost. | ||||
| 289 | +- H4: persistent state and recovery rules improve valid continuation after standardized interruptions. | ||||
| 290 | +- H5: benefits vary by task family and task complexity. | ||||
| 291 | +- H6: human preparation and review costs materially change the apparent efficiency gains. | ||||
| 292 | + | ||||
| 293 | +These hypotheses are not guaranteed directions of effect. Report uncertainty and counterevidence. | ||||
| 294 | + | ||||
| 295 | +### 7.1 Primary endpoint | ||||
| 296 | + | ||||
| 297 | +Use intervention-free science-verified completion within the assigned budget as the primary binary endpoint, unless the pilot reveals a defensible reason to amend before confirmatory evaluation. | ||||
| 298 | + | ||||
| 299 | +For task instance i, arm a, repeat r: | ||||
| 300 | + | ||||
| 301 | +Y_iar = 1{required scientific criteria satisfied, no critical integrity violation, no substantive human intervention, within resource envelope}. | ||||
| 302 | + | ||||
| 303 | +The criteria must be task-specific, defined in advance and evaluated outside the executor. A complete-looking report that is wrong scores zero. A correct result after assistance is recorded as assisted success, not unassisted success. Appropriate recognition of an intentionally infeasible task is evaluated under that task's predeclared rubric and reported separately from completion of feasible tasks. | ||||
| 304 | + | ||||
| 305 | +Do not make a verbose refusal or an empty output score highly by avoiding claims. Fixed required scientific outputs remain in the denominator. | ||||
| 306 | + | ||||
| 307 | +### 7.2 Secondary endpoints | ||||
| 308 | + | ||||
| 309 | +- Scientifically correct completion, with and without assistance. | ||||
| 310 | +- Fixed-rubric scientific-quality score and its component scores. | ||||
| 311 | +- Critical integrity violations: leakage, fabrication, invalid inference, unreported data substitution, false completion or corrupted provenance. | ||||
| 312 | +- Unsupported central claims and errors per required claim set. | ||||
| 313 | +- Additional unsupported claims introduced voluntarily, reported separately. | ||||
| 314 | +- Fresh-environment reproducibility success and numerical agreement. | ||||
| 315 | +- Correct detection of blocked or invalid tasks; false blocking on feasible tasks. | ||||
| 316 | +- Recovery success, duplicate jobs, lost artifacts and stale-result reuse. | ||||
| 317 | +- Latency, total inference usage, actual known costs and human minutes. | ||||
| 318 | +- Cost per assigned task and cost per verified completion, with undefined ratios reported when no task succeeds. | ||||
| 319 | + | ||||
| 320 | +Report instrument coverage and missing measurements. Do not quietly infer missing usage or exact cost from a rough wall-clock estimate. | ||||
| 321 | + | ||||
| 322 | +## 8. Experimental treatments and fairness | ||||
| 323 | + | ||||
| 324 | +### 8.1 Four main arms | ||||
| 325 | + | ||||
| 326 | +| Arm | Intervention | What is deliberately absent | | ||||
| 327 | +|---|---|---| | ||||
| 328 | +| A — Open instruction | Scientific task and common evidence packet, standard common access and budget | No prescribed phase structure, no mandatory runtime scientific gates, no separate review stage | | ||||
| 329 | +| B — Structured protocol | Same task facts and resources, plus explicit phases, evidence requirements, stopping and recovery instructions | No externally mandatory runtime scientific gate feedback and no separate review stage | | ||||
| 330 | +| C — Protocol plus gates | Arm B plus executable runtime gates and controlled state transitions | No separate reviewer beyond common final evaluation | | ||||
| 331 | +| D — Protocol plus gates and review | Arm C plus a separately configured review-and-repair stage | No additional factual evidence, hidden labels or unrestricted extra resources | | ||||
| 332 | + | ||||
| 333 | +All arms receive the same substantive scientific question, accessible input data, relevant task definitions, output obligations and common safety/integrity constraints. Do not construct A by deleting information necessary to solve the task. The experimental intervention changes how the work is organized and checked. | ||||
| 334 | + | ||||
| 335 | +Provide all arms with the same common final outcome evaluation after submission. That evaluator is distinct from the runtime gate feedback offered only to the relevant arms. Its hidden answers are never returned to workers. An executor in A or B may voluntarily write and run tests; record this rather than forbidding competent behavior. | ||||
| 336 | + | ||||
| 337 | +### 8.2 Shared resource envelope | ||||
| 338 | + | ||||
| 339 | +Match model identity, available tools, scientific input information, wall-time ceiling, total inference budget and computational allowance as closely as the platform permits. In D, reviewer calls consume the same total envelope rather than free additional compute. Keep an explicit accounting of executor and reviewer costs. | ||||
| 340 | + | ||||
| 341 | +Report both equal-budget comparisons and, when feasible, quality-cost frontiers across prespecified budgets. A more complex method may spend more on instructions or checks; that overhead is part of the treatment cost, not something to hide. | ||||
| 342 | + | ||||
| 343 | +### 8.3 Length and information controls | ||||
| 344 | + | ||||
| 345 | +Add a secondary long-form, unstructured instruction control or a matched-content comparison to distinguish structure from extra scientific information and instruction length. Do not add meaningless padding merely to match token counts. Publish arm prompts, a content-equivalence audit and measured initial-context sizes. | ||||
| 346 | + | ||||
| 347 | +Treat this as a separate ablation if including it would exceed the primary budget. Do not imply the four main arms fully identify a "pure effect of structure" when content, feedback and computational allocation also differ. | ||||
| 348 | + | ||||
| 349 | +### 8.4 Randomization and temporal blocking | ||||
| 350 | + | ||||
| 351 | +Use paired task instances across arms. Randomize arm order and block by task, execution window and supported model version. Avoid running all baseline tasks first and all full-method tasks after a provider update. Independent repeats use fresh sessions and clean workspaces; changing only a directory name is not enough. | ||||
| 352 | + | ||||
| 353 | +Fixed seeds can control task generation and deterministic tools. They may not control hosted model stochasticity. Preserve actual repeat outcomes and document the limits of deterministic replication. | ||||
| 354 | + | ||||
| 355 | +## 9. Benchmark suite with scientifically meaningful tasks | ||||
| 356 | + | ||||
| 357 | +Build six families with explicit scoring oracles and artifact requirements. Favor bounded tasks that require scientific reasoning, data handling and evidence, rather than arbitrary coding puzzles. | ||||
| 358 | + | ||||
| 359 | +F1 Data provenance and audit | ||||
| 360 | + | ||||
| 361 | +Examples: duplicate entities, inconsistent units, unavailable-at-origin variables, a changing sample universe, timestamp shifts, and a corrupted input file. Tasks should require a documented analytic dataset and an exclusion ledger, not only bug discovery. | ||||
| 362 | + | ||||
| 363 | +Reference evaluation: independently computed counts, unit conversions, temporal constraints and permitted exclusion rules. Preserve legitimate variation in implementation. | ||||
| 364 | + | ||||
| 365 | +F2 Estimation and statistical inference | ||||
| 366 | + | ||||
| 367 | +Examples: reproduce a regression with specified fixed effects; select uncertainty estimates under a known dependence design; detect a deliberately inappropriate standard error; perform a Monte Carlo coverage analysis. | ||||
| 368 | + | ||||
| 369 | +Use analytical or independently coded references where possible. Define numerical tolerances from mathematical or statistical reasoning. For stochastic quantities, compare with uncertainty rather than demanding identical last decimals. | ||||
| 370 | + | ||||
| 371 | +F3 Forecasting and temporal information | ||||
| 372 | + | ||||
| 373 | +Examples: rolling-origin evaluation on a public economic series; a feature with release lag; revised target data; a future-informed normalization step; forecasting at multiple horizons with overlapping targets. | ||||
| 374 | + | ||||
| 375 | +Require a simple valid baseline and untouched evaluation information. Reference checks must verify chronology, not just score prediction accuracy. Do not claim historical real-time validity from a single final-vintage dataset. | ||||
| 376 | + | ||||
| 377 | +F4 Source-grounded evidence synthesis | ||||
| 378 | + | ||||
| 379 | +Use accessible full-text sources with verifiable tables or claims. Tasks can involve extracting coefficients and uncertainties, checking whether a cited source supports an assertion, and separating incompatible effect-size definitions. | ||||
| 380 | + | ||||
| 381 | +Reference evaluation requires page/table locators and independently checked values. Respect source rights. Do not infer that a citation exists because a generated DOI looks plausible. If human annotation is unavailable, identify the alternative reference process and its uncertainty. | ||||
| 382 | + | ||||
| 383 | +F5 Theory, mechanisms and numerical validation | ||||
| 384 | + | ||||
| 385 | +Examples: a tractable equilibrium with a budget identity, a statistical estimator with a known bias property, a proposed statement admitting a counterexample, or a numerical solver with a known limiting solution. | ||||
| 386 | + | ||||
| 387 | +Require explicit assumptions and correct scope. A large simulation does not prove a universal statement. Use exact small cases and deliberately broken identities to test validators. Formal verification is optional when feasible, not something to claim without an actual proof-checker run. | ||||
| 388 | + | ||||
| 389 | +F6 Integrated scientific mini-projects | ||||
| 390 | + | ||||
| 391 | +Require a complete bounded chain: question, data/source audit, benchmark, justified method, results, uncertainty, failure discussion, generated table/figure and short report. Include at least one genuine negative result or invalid-premise task designed before evaluation. | ||||
| 392 | + | ||||
| 393 | +Evaluate the chain and the scientific interpretation. Do not let attractive prose compensate for wrong calculations. Keep this family sufficiently substantial to distinguish autonomous scientific execution from a collection of unit-test coding exercises. | ||||
| 394 | + | ||||
| 395 | +### 9.1 Data sources and representativeness | ||||
| 396 | + | ||||
| 397 | +Use real, publicly accessible research data and primary documents for a substantial part of the suite. At the target scale, aim for at least eight real-data tasks and four genuine source-document tasks; classify overlapping categories and report counts clearly. Select actual datasets after verifying access, provenance, license, schema and suitability. Possible families include official economic time series, open statistical datasets and openly reproducible published analyses. These are candidates, not assertions that particular endpoints are available. | ||||
| 398 | + | ||||
| 399 | +Synthetic tasks with known truth remain scientifically useful for measurement and stress testing, but must be labeled. "Real experiment" refers to actual agent execution; distinguish that from whether the task uses observed or synthetic data. | ||||
| 400 | + | ||||
| 401 | +Maintain tasks/task_cards/ with a card for each instance: question, data type, scope, prerequisites, allowed information, expected artifacts, rubric, oracle provenance, difficulty rationale, budget, failure modes and contamination risk. | ||||
| 402 | + | ||||
| 403 | +### 9.2 Split and leakage controls | ||||
| 404 | + | ||||
| 405 | +Use separate development, pilot and confirmatory task sets. Do not tune the protocol or validators against the final outcomes. Freeze task and oracle versions before the final evaluation. Executor sessions cannot access sibling outputs, previous attempts, scoring keys or the manuscript's results section. | ||||
| 406 | + | ||||
| 407 | +For externally published tasks, report possible pretraining contamination. Newly generated parameters reduce direct answer copying but do not eliminate familiarity with the underlying problem. For internally authored tasks, report evaluator/designer dependence rather than claiming external independence. | ||||
| 408 | + | ||||
| 409 | +## 10. Scale, budget and stopping design | ||||
| 410 | + | ||||
| 411 | +### 10.1 Staged plan | ||||
| 412 | + | ||||
| 413 | +Treat the following as planning configurations, not completed counts or automatic power justifications: | ||||
| 414 | + | ||||
| 415 | +| Stage | Proposed configuration | Live task executions | | ||||
| 416 | +|---|---|---:| | ||||
| 417 | +| Capability smoke test | 1 development task × 4 arms × 1 repeat | 4 | | ||||
| 418 | +| Development pilot | 6 separate development tasks × 4 arms × 1 repeat | 24 | | ||||
| 419 | +| Main task benchmark target | 24 confirmatory tasks × 4 arms × 3 repeats | 288 | | ||||
| 420 | +| End-to-end transfer study target | 3 new mini-projects × 4 arms × 2 repeats | 24 | | ||||
| 421 | + | ||||
| 422 | +The target task benchmark comprises four tasks in each of six families. The transfer mini-projects are additional held-out projects, not relabeled repetitions of F6 tasks. A reviewer stage in D can require multiple sessions; distinguish task executions from session counts and API calls. | ||||
| 423 | + | ||||
| 424 | +Before scaling, measure actual pilot costs and durations. Account for instruction tokens, retries, compilation, capture overhead, reviewer calls, evaluator time and human preparation. Estimate a resource envelope with a documented contingency allowance. Reuse existing explicit budgets. If indispensable paid capacity has not been authorized, obtain a precise budget decision rather than launching an uncapped run. | ||||
| 425 | + | ||||
| 426 | +If resources support only a smaller study, define and freeze a reduced design before examining confirmatory outcomes. A possible exploratory configuration is 12 tasks × 4 arms × 2 repeats, with explicit limits. Do not describe this as automatically sufficient for confirmatory inference. Report reduced coverage and uncertainty. | ||||
| 427 | + | ||||
| 428 | +### 10.2 Precision and power | ||||
| 429 | + | ||||
| 430 | +Use development-only estimates or justified scenarios to assess detectable differences and interval widths at the task-cluster level. Increasing repeats of the same small task set does not create the same scientific coverage as more independent tasks. | ||||
| 431 | + | ||||
| 432 | +Choose the final design based on feasible precision, cost and domain coverage. Preserve the design decision and simulation code. Do not continue adding runs until a preferred effect becomes significant. | ||||
| 433 | + | ||||
| 434 | +### 10.3 Stopping and exclusions | ||||
| 435 | + | ||||
| 436 | +Set time, cost, call and retry limits before a run. A scientific failure remains a failure. Infrastructure outages have a separate status and a predeclared policy for balanced reruns. Retain every assigned run in the registry and report intention-to-treat results alongside any justified sensitivity analysis. | ||||
| 437 | + | ||||
| 438 | +Do not silently remove failed, slow or embarrassing executions. Report assigned tasks, launched runs, completed runs, evaluated runs, scientific successes and missing measurements separately. | ||||
| 439 | + | ||||
| 440 | +## 11. End-to-end transfer study | ||||
| 441 | + | ||||
| 442 | +Conduct real bounded research projects beyond the short benchmark. Suggested designs, to finalize after data access checks: | ||||
| 443 | + | ||||
| 444 | +1. Empirical forecasting project: a public economic series with explicit availability dates, rolling evaluation, naive and statistical baselines, uncertainty and a short paper. | ||||
| 445 | +2. Simulation-methodology project: a finite-sample estimator comparison with known analytical properties, Monte Carlo uncertainty, failure regimes and an executable technical note. | ||||
| 446 | +3. Evidence-synthesis project: a small set of accessible primary studies requiring source extraction, careful harmonization and an appropriately limited synthesis. | ||||
| 447 | + | ||||
| 448 | +Require a research report, actual calculations, provenance, generated plots/tables and a replication entry point. Set a bounded scope so all arms have a plausible opportunity within the shared resource envelope. Do not demand a novel top-journal discovery as a binary scoring criterion. | ||||
| 449 | + | ||||
| 450 | +Use the same outcome rubric across arms within each mini-project. Report transfer results separately from the task benchmark. With only a few projects, emphasize case-level results and limited generalization; do not turn many generated files into fictitious independent sample units. | ||||
| 451 | + | ||||
| 452 | +The fact that WP29 itself is produced under this mandate is an additional instrumented case study. It is not an independent confirmatory observation and must not be pooled with the randomized benchmark as such. | ||||
| 453 | + | ||||
| 454 | +## 12. Stress tests and mechanism ablations | ||||
| 455 | + | ||||
| 456 | +Implement standardized, harmless faults inside isolated research workspaces. Examples: | ||||
| 457 | + | ||||
| 458 | +- Interrupt a worker after a known checkpoint, then resume it. | ||||
| 459 | +- Remove access to an explicitly required local fixture. | ||||
| 460 | +- Change a non-secret upstream data file and test stale-output invalidation. | ||||
| 461 | +- Introduce a duplicate job submission request and test idempotency. | ||||
| 462 | +- Supply a deliberately inconsistent unit or timestamp in a labeled evaluation fixture. | ||||
| 463 | +- Return a controlled transient error from a test service adapter. | ||||
| 464 | +- Make a previously plausible citation fail source verification. | ||||
| 465 | +- Present a scientific hypothesis for which the reference result is null or negative. | ||||
| 466 | + | ||||
| 467 | +Never corrupt real user data or unrelated repositories. Fault injection is part of an experimental condition and must be logged outside the executor. If a service failure is simulated while Claude Code execution is live, state both facts precisely. | ||||
| 468 | + | ||||
| 469 | +Predefine the intervention point, fault severity, allowable recovery actions and success criteria. Compare recovery against a matched no-fault run where feasible. Separate "recognized a blockage" from "completed the intended research despite the fault." | ||||
| 470 | + | ||||
| 471 | +Mechanism ablations can remove one component from PGAR: persistent state, mandatory gates, claim ledger, explicit failure rules or review. Use matched information and budgets. Avoid an enormous factorial design that is impossible to interpret or afford. Select the most informative ablations before final results. | ||||
| 472 | + | ||||
| 473 | +## 13. Evaluation validity and human involvement | ||||
| 474 | + | ||||
| 475 | +### 13.1 Independent outcome evaluation | ||||
| 476 | + | ||||
| 477 | +Use task-specific deterministic checks where scientific truth is available. For interpretive outputs, combine a frozen rubric with source verification and a clearly identified review process. Human expert review is desirable for a prespecified sample of central claims and proof tasks when actual reviewers are available and authorized. | ||||
| 478 | + | ||||
| 479 | +Do not fabricate human scores, consent, credentials or recruitment. If no human reviewers participate, label those cells unavailable and disclose the resulting limitation. A simulated economist role is not a human economist. | ||||
| 480 | + | ||||
| 481 | +Model-based grading may be a supplementary measure. Record the grading model, prompts, context, rubric and response. Test graders against seeded correct and incorrect artifacts; report false acceptance and false rejection. A same-family model grader may share systematic errors with the executor. | ||||
| 482 | + | ||||
| 483 | +### 13.2 Blinding and rubric design | ||||
| 484 | + | ||||
| 485 | +Use neutral run IDs and remove explicit treatment labels from scoring bundles when feasible. Some artifacts may reveal the treatment; document imperfect blinding. Do not claim a blinded evaluation if the grader can plainly see arm labels or prior results. | ||||
| 486 | + | ||||
| 487 | +Grade required scientific outputs, not generic writing quality alone. Specify critical failures that cannot be offset by a polished report. A quality score can summarize components, but its weights are frozen before final scoring and its components are also reported. | ||||
| 488 | + | ||||
| 489 | +### 13.3 Human intervention ledger | ||||
| 490 | + | ||||
| 491 | +Record preparation, configuration, troubleshooting, scientific guidance, direct file edits, evaluator construction, screenshot curation and final review. Log actor, timestamp, phase/run, intervention category, duration if measured and scientific impact. | ||||
| 492 | + | ||||
| 493 | +If historical preparation time is unknown, state that it is unknown. Do not reconstruct exact minutes from memory. Distinguish observed time, instrumented estimates and unmeasured effort. A one-time setup cost may be amortized under explicit scenarios, with the unamortized cost also shown. | ||||
| 494 | + | ||||
| 495 | +## 14. Statistical analysis plan | ||||
| 496 | + | ||||
| 497 | +### 14.1 Unit of analysis and estimands | ||||
| 498 | + | ||||
| 499 | +The execution is indexed by task, arm and repeat, but repetitions within a task are dependent. Report task-level paired effects and family-level heterogeneity. The main estimand is the average difference in intervention-free verified completion between specified arms over the evaluated task distribution, not all possible scientific research. | ||||
| 500 | + | ||||
| 501 | +Define the primary contrast in advance, for example D versus A. Treat B versus A, C versus B and D versus C as prespecified mechanism contrasts, with appropriate multiplicity handling or explicit secondary status. | ||||
| 502 | + | ||||
| 503 | +For a task-weighted completion estimate, use: | ||||
| 504 | + | ||||
| 505 | +p̂_a = (1/J) Σ_{j=1}^{J} ( (1/R_j) Σ_{r=1}^{R_j} Y_{jar} ), Δ̂_ab = p̂_a − p̂_b. | ||||
| 506 | + | ||||
| 507 | +State the weights, treatment of unequal repeats and missingness. Do not allow a heavily repeated easy task to dominate by accident. | ||||
| 508 | + | ||||
| 509 | +### 14.2 Uncertainty | ||||
| 510 | + | ||||
| 511 | +Use task-cluster bootstrap or randomization/permutation procedures appropriate to the assignment mechanism and sample size. With few clusters, report their limitations and avoid relying on asymptotic normal approximations alone. Hierarchical models may be sensitivity analyses if their assumptions and priors are explicit. | ||||
| 512 | + | ||||
| 513 | +Do not treat screenshots, paragraphs, tool calls or multiple rubric items from one run as independent experimental subjects. For claim-level error analyses, retain task/run dependence. | ||||
| 514 | + | ||||
| 515 | +### 14.3 Cost, time and failure | ||||
| 516 | + | ||||
| 517 | +Report distributions, not only averages. Provide medians, tails, success-conditioned and unconditional quantities where informative, with clear denominators. Report completion by the common deadline; treat unfinished task times as censored when using time-to-completion methods rather than recording timeout as successful completion. | ||||
| 518 | + | ||||
| 519 | +Show costs per assigned run and total resources spent, including failed attempts. Separate setup costs, experimental inference, review, deterministic evaluation and documentation overhead. If billing is subscription-based or exact run cost cannot be attributed, use observed usage/time and transparent accounting scenarios instead of invented dollar amounts. | ||||
| 520 | + | ||||
| 521 | +### 14.4 Robustness | ||||
| 522 | + | ||||
| 523 | +At minimum assess sensitivity to task family, complexity, failure definitions, budget, uncertain rubric labels and alternative reasonable aggregation. Add model/version replication when feasible and label it exploratory if not preregistered. | ||||
| 524 | + | ||||
| 525 | +Run negative-control analyses and data-quality assertions on the analysis dataset. Independently recalculate headline table cells. All manuscript numbers must come from saved outputs with identifiers and uncertainty. | ||||
| 526 | + | ||||
| 527 | +## 15. Real screenshots and visual evidence are mandatory | ||||
| 528 | + | ||||
| 529 | +### 15.1 What must be captured | ||||
| 530 | + | ||||
| 531 | +Create authentic visual records of the actual experiment and the implemented system: | ||||
| 532 | + | ||||
| 533 | +1. Environment/version verification in the research-only terminal or client. | ||||
| 534 | +2. An actual task's assigned protocol and effective treatment configuration. | ||||
| 535 | +3. A real Claude Code execution while it is operating on a task. | ||||
| 536 | +4. Actual generated code or data artifact tied to that run. | ||||
| 537 | +5. A real gate rejection or test failure, when one occurs or is deliberately induced in a labeled stress test. | ||||
| 538 | +6. A real correction and rerun, with distinct before/after event IDs. | ||||
| 539 | +7. A real interruption/recovery sequence in the dedicated recovery experiment. | ||||
| 540 | +8. The experiment-status dashboard showing actual registered runs. | ||||
| 541 | +9. A generated results table or plot backed by the frozen analysis data. | ||||
| 542 | +10. The compiled WP29 manuscript and evidence/replication inventory. | ||||
| 543 | + | ||||
| 544 | +Do not fabricate an error to make the main experiment look dramatic. Controlled fault-injection evidence is welcome but must be labeled as such. | ||||
| 545 | + | ||||
| 546 | +### 15.2 Acceptable capture modes | ||||
| 547 | + | ||||
| 548 | +- Native live capture: an actual research terminal, Claude Code UI or research application captured with permitted OS/browser tools. | ||||
| 549 | +- Live evidence dashboard capture: a browser screenshot of a real local dashboard populated from the actual event store while runs execute. | ||||
| 550 | +- Post-run evidence viewer capture: a screenshot of a real viewer showing archived run data; explicitly label it post-run. | ||||
| 551 | +- Transcript replay: optional rendering of a recorded terminal session, explicitly labeled replay and not substituted for a live UI capture. | ||||
| 552 | + | ||||
| 553 | +Use the capture tools available on the verified platform. On a headless environment, implement a simple browser evidence viewer over real event data and use a genuine browser screenshot. If a native Claude Code UI cannot be captured, report that limit and distinguish dashboard captures from native screenshots. Do not imply that a screenshot of an HTML imitation of a terminal is a native Claude session. | ||||
| 554 | + | ||||
| 555 | +Do not use image-generation tools to create evidence. Do not manufacture terminal output, timestamps, charts, progress bars, chat bubbles or successful tests. Diagrams can be programmatically drawn, but label them as diagrams rather than observations. | ||||
| 556 | + | ||||
| 557 | +### 15.3 Capture contract | ||||
| 558 | + | ||||
| 559 | +Implement a capture mechanism with configured event triggers rather than relying exclusively on handpicked successes. For each image record: | ||||
| 560 | + | ||||
| 561 | +screenshot_id; run_id and task_id; treatment and phase; event_id or event-range linkage; capture_timestamp_utc; capture_mode: native_live / dashboard_live / viewer_postrun / transcript_replay; capture_tool and version; source_surface or local URL; original_path and SHA-256; redacted_public_path and SHA-256, if applicable; redaction/crop description; selection_rule; caption and claim IDs illustrated. | ||||
| 562 | + | ||||
| 563 | +Hashing shows file integrity relative to the recorded manifest; it does not independently prove when or how the image was captured. Triangulate screenshots with event timestamps, logs, process IDs and artifact hashes. Describe their evidentiary limits. | ||||
| 564 | + | ||||
| 565 | +### 15.4 Privacy and presentation | ||||
| 566 | + | ||||
| 567 | +Capture only the research workspace and necessary application regions. Exclude secrets, private messages, unrelated windows and personal information. Prefer preventing sensitive content from entering the capture at all. Keep authorized originals in restricted storage; create separately hashed public redactions when needed and document what was removed. Never alter scientific values or hide an error to improve appearance. | ||||
| 568 | + | ||||
| 569 | +Produce a prespecified audit gallery. For example, capture fixed milestones for a stratified subset of task families and arms, plus all fault-injection milestones. Set storage bounds. Report missing captures and capture failures. Screenshots document events; they are not independent samples for inference. | ||||
| 570 | + | ||||
| 571 | +Use selected readable screenshots in the main paper and a fuller gallery in an appendix or evidence supplement. Provide captions with run ID, treatment, event, capture mode and what the image does and does not establish. | ||||
| 572 | + | ||||
| 573 | +## 16. Experiment records and evidence schemas | ||||
| 574 | + | ||||
| 575 | +Use explicit schemas and schema validation. Prefer structured records to prose-only logs. | ||||
| 576 | + | ||||
| 577 | +### 16.1 Run manifest | ||||
| 578 | + | ||||
| 579 | +At minimum: | ||||
| 580 | + | ||||
| 581 | +```json | ||||
| 582 | +{ | ||||
| 583 | + "run_id": "generated_by_harness", | ||||
| 584 | + "task_id": "frozen_task_identifier", | ||||
| 585 | + "split": "development_or_pilot_or_confirmatory_or_transfer", | ||||
| 586 | + "treatment": "A_or_B_or_C_or_D", | ||||
| 587 | + "repeat_index": 0, | ||||
| 588 | + "task_hash": null, | ||||
| 589 | + "protocol_hash": null, | ||||
| 590 | + "effective_context_hash": null, | ||||
| 591 | + "code_commit": null, | ||||
| 592 | + "environment_id": null, | ||||
| 593 | + "client_version": null, | ||||
| 594 | + "model_requested": null, | ||||
| 595 | + "model_reported": null, | ||||
| 596 | + "session_ids": [], | ||||
| 597 | + "started_at_utc": null, | ||||
| 598 | + "ended_at_utc": null, | ||||
| 599 | + "status": "not_started", | ||||
| 600 | + "budget": {}, | ||||
| 601 | + "usage": {}, | ||||
| 602 | + "human_intervention_ids": [], | ||||
| 603 | + "artifact_manifest": null, | ||||
| 604 | + "evaluation_receipt": null, | ||||
| 605 | + "screenshot_ids": [] | ||||
| 606 | +} | ||||
| 607 | +``` | ||||
| 608 | + | ||||
| 609 | +This is a schema illustration, not an example completed run. Replace null fields from actual observations. Validate required fields at each state transition; unavailable metadata must be explicitly classified rather than filled with invented values. | ||||
| 610 | + | ||||
| 611 | +### 16.2 Event stream | ||||
| 612 | + | ||||
| 613 | +Record unique event ID, run/session ID, UTC timestamp, monotonic elapsed time where available, event type, tool/phase, status, artifact references, duration, usage and error classification. Keep raw authorized provider output and normalized records separate. Never log authentication material. | ||||
| 614 | + | ||||
| 615 | +### 16.3 Scientific claim ledger | ||||
| 616 | + | ||||
| 617 | +Record claim ID, exact text, claim type, scope, hypothesis, task/run or proof/source IDs, evidence paths, evaluation status, assumptions, uncertainty, manuscript location and amendments. Separate the claims made by experimental agents from claims made by the WP29 authors about the experiment. | ||||
| 618 | + | ||||
| 619 | +### 16.4 Dataset and transformation ledger | ||||
| 620 | + | ||||
| 621 | +Record snapshot hashes, origin, retrieval time, units, schema, information-availability rule, license, parent artifacts, transformations and exclusions. Evaluation oracles have a separate protected ledger inaccessible to workers. | ||||
| 622 | + | ||||
| 623 | +### 16.5 Intervention and amendment ledgers | ||||
| 624 | + | ||||
| 625 | +Record every substantive human change and every alteration to a frozen design. Preserve previous versions and identify whether a change was made before or after seeing results. Frozen confirmatory results must not be overwritten by exploratory reruns. | ||||
| 626 | + | ||||
| 627 | +## 17. Repository structure | ||||
| 628 | + | ||||
| 629 | +Adapt to existing UQO conventions while preserving the following functional separation: | ||||
| 630 | + | ||||
| 631 | +``` | ||||
| 632 | +wp29-autonomous-research/ | ||||
| 633 | + CLAUDE.md | ||||
| 634 | + README.md | ||||
| 635 | + Makefile | ||||
| 636 | + pyproject.toml | ||||
| 637 | + environment.lock | ||||
| 638 | + .env.example | ||||
| 639 | + protocol/ | ||||
| 640 | + WP29_FULL_MANDATE.md | ||||
| 641 | + preregistration.md | ||||
| 642 | + scientific_contract.md | ||||
| 643 | + treatment_definitions.md | ||||
| 644 | + evaluation_plan.md | ||||
| 645 | + screenshot_protocol.md | ||||
| 646 | + amendments.csv | ||||
| 647 | + research/ | ||||
| 648 | + corpus_manifest.csv | ||||
| 649 | + corpus_coding.csv | ||||
| 650 | + literature_matrix.csv | ||||
| 651 | + novelty_matrix.csv | ||||
| 652 | + source_notes.md | ||||
| 653 | + configs/ | ||||
| 654 | + development.yaml | ||||
| 655 | + pilot.yaml | ||||
| 656 | + confirmatory.yaml | ||||
| 657 | + transfer.yaml | ||||
| 658 | + budgets.yaml | ||||
| 659 | + capture.yaml | ||||
| 660 | + tasks/ | ||||
| 661 | + registry.csv | ||||
| 662 | + task_cards/ | ||||
| 663 | + public_bundles/ | ||||
| 664 | + src/pgar/ | ||||
| 665 | + contracts.py | ||||
| 666 | + scheduler.py | ||||
| 667 | + state.py | ||||
| 668 | + launcher.py | ||||
| 669 | + isolation.py | ||||
| 670 | + events.py | ||||
| 671 | + provenance.py | ||||
| 672 | + budgets.py | ||||
| 673 | + recovery.py | ||||
| 674 | + runtime_gates.py | ||||
| 675 | + capture.py | ||||
| 676 | + evidence_viewer.py | ||||
| 677 | + exports.py | ||||
| 678 | + evaluators/ | ||||
| 679 | + README.md | ||||
| 680 | + public_evaluation_interface/ | ||||
| 681 | + tests/ | ||||
| 682 | + unit/ | ||||
| 683 | + integration/ | ||||
| 684 | + isolation/ | ||||
| 685 | + invalid_artifacts/ | ||||
| 686 | + runs/ | ||||
| 687 | + development/ | ||||
| 688 | + pilot/ | ||||
| 689 | + confirmatory/ | ||||
| 690 | + transfer/ | ||||
| 691 | + evidence/ | ||||
| 692 | + manifests/ | ||||
| 693 | + public_screenshots/ | ||||
| 694 | + public_traces/ | ||||
| 695 | + galleries/ | ||||
| 696 | + analysis/ | ||||
| 697 | + build_analysis_dataset.py | ||||
| 698 | + primary_analysis.py | ||||
| 699 | + robustness.py | ||||
| 700 | + figures.py | ||||
| 701 | + tables.py | ||||
| 702 | + results/ | ||||
| 703 | + analysis_data/ | ||||
| 704 | + estimates/ | ||||
| 705 | + figures/ | ||||
| 706 | + tables/ | ||||
| 707 | + reports/ | ||||
| 708 | + phase_status.md | ||||
| 709 | + interventions.csv | ||||
| 710 | + environment_audit.md | ||||
| 711 | + isolation_audit.md | ||||
| 712 | + evaluator_validation.md | ||||
| 713 | + pilot_report.md | ||||
| 714 | + experiment_accounting.md | ||||
| 715 | + failure_analysis.md | ||||
| 716 | + final_review.md | ||||
| 717 | + reproducibility_report.md | ||||
| 718 | + paper/ | ||||
| 719 | + main.tex | ||||
| 720 | + references.bib | ||||
| 721 | + sections/ | ||||
| 722 | + appendices/ | ||||
| 723 | + figures/ | ||||
| 724 | + tables/ | ||||
| 725 | + release/ | ||||
| 726 | +``` | ||||
| 727 | + | ||||
| 728 | +Hidden evaluation material and restricted originals live outside all executor-accessible mounts. The repository tree alone does not enforce that boundary. Document the actual external evaluator storage and access controls without revealing secrets. | ||||
| 729 | + | ||||
| 730 | +## 18. Figures required for the research paper | ||||
| 731 | + | ||||
| 732 | +Generate each quantitative figure from the frozen analysis dataset. Include uncertainty and sample counts where relevant. Use vector output for charts and diagrams, and native-resolution raster images for screenshots. Do not substitute screenshots of plots for reproducible plotting scripts. | ||||
| 733 | + | ||||
| 734 | +Target figure set, retaining only figures supported by completed work: | ||||
| 735 | + | ||||
| 736 | +1. Method architecture: researcher contract, executor, runtime gates, persistent state, evaluator and evidence store; clearly show trust boundaries. | ||||
| 737 | +2. Experimental design: task splits, treatment assignment, repeated executions, budget matching and final evaluation. | ||||
| 738 | +3. Phase and evidence graph: actual artifact dependencies and invalidation paths in the implemented method. | ||||
| 739 | +4. Primary completion comparison: arm-level and task-paired effects with uncertainty. | ||||
| 740 | +5. Scientific-quality and integrity outcomes: component scores and critical failure rates. | ||||
| 741 | +6. Quality-cost frontier: actual usage/cost and scientific outcomes under declared budgets. | ||||
| 742 | +7. Task-family heterogeneity: paired effects or completion rates by family, with sample sizes. | ||||
| 743 | +8. Recovery experiment: observed event timeline and recovery outcomes under standardized faults. | ||||
| 744 | +9. Human-effort decomposition: preparation, execution assistance and review, with unknown amounts visible. | ||||
| 745 | +10. Authentic screenshot case study: protocol, live run, detected failure, correction and verified artifact, tied to event IDs. | ||||
| 746 | +11. Error taxonomy: rates of distinct scientifically meaningful errors; permit multiple errors per run without mislabeling the denominator. | ||||
| 747 | +12. Transfer mini-projects: case-level results and evidence coverage. | ||||
| 748 | +13. Ablations or sensitivity: selected component removals and alternative scoring assumptions. | ||||
| 749 | +14. WP29 reflexive execution trace: a descriptive account of how this paper was produced, clearly separated from confirmatory evidence. | ||||
| 750 | + | ||||
| 751 | +Do not force fourteen figures if fewer experiments support fewer figures. A complete evidence gallery belongs in the supplement, not in an unreadable main-paper collage. | ||||
| 752 | + | ||||
| 753 | +## 19. Tables required for the research paper | ||||
| 754 | + | ||||
| 755 | +Produce executable tables with explicit denominators, units, statuses and notes: | ||||
| 756 | + | ||||
| 757 | +1. Closest prior systems and the precise contribution relative to them. | ||||
| 758 | +2. Source mandate corpus and coded design features. | ||||
| 759 | +3. Scientific contract components, implementation and verification mechanisms. | ||||
| 760 | +4. Task suite, domains, data type, reference-answer provenance and difficulty. | ||||
| 761 | +5. Treatment differences, common information, tools, budgets and context sizes. | ||||
| 762 | +6. Assignment and execution accounting: planned, assigned, launched, completed, failed, blocked and evaluated. | ||||
| 763 | +7. Primary endpoint, effect sizes, uncertainty and task-cluster counts. | ||||
| 764 | +8. Scientific-quality components and integrity violations. | ||||
| 765 | +9. Runtime, usage, cost and success-conditioned efficiency with honest accounting. | ||||
| 766 | +10. Recovery and fault-injection outcomes, including false blocking. | ||||
| 767 | +11. Ablations, length/information controls and robustness analyses. | ||||
| 768 | +12. End-to-end mini-project results and verified artifacts. | ||||
| 769 | +13. Human interventions and preparation/review effort. | ||||
| 770 | +14. Limitations, unresolved risks and the scope of claims actually supported. | ||||
| 771 | + | ||||
| 772 | +Save table source data and code alongside LaTeX outputs. No manual numeric editing in the manuscript. Missing values are labeled with a reason; zero, unavailable and not attempted are different states. | ||||
| 773 | + | ||||
| 774 | +## 20. Manuscript requirements | ||||
| 775 | + | ||||
| 776 | +Produce an English research article suitable for serious review in AI-for-science, agent evaluation, research methods or computational research infrastructure. It must be an argument supported by experiments, not a user manual padded into a paper. | ||||
| 777 | + | ||||
| 778 | +Suggested structure: | ||||
| 779 | + | ||||
| 780 | +1. Introduction: scientific motivation, question, contribution and actual findings. | ||||
| 781 | +2. Related work: autonomous research, agent evaluation, workflows and reproducibility. | ||||
| 782 | +3. Conceptual framework: delegation contract, autonomy and evidence. | ||||
| 783 | +4. Corpus-informed method design: what the prior mandates motivate and cannot establish. | ||||
| 784 | +5. PGAR implementation: contracts, phases, controls, state, isolation and evidence. | ||||
| 785 | +6. Experimental design: tasks, treatments, budgets, randomization and estimands. | ||||
| 786 | +7. Evaluation: scientific rubrics, protected oracles, intervention measurement and uncertainty. | ||||
| 787 | +8. Main results: completion, quality, integrity and resources. | ||||
| 788 | +9. Recovery, ablations and failure analysis. | ||||
| 789 | +10. End-to-end transfer and authentic visual case studies. | ||||
| 790 | +11. Reflexive analysis of the WP29 production process. | ||||
| 791 | +12. Limitations, reproducibility and implications for scientific practice. | ||||
| 792 | +13. Conclusion proportional to the evidence. | ||||
| 793 | + | ||||
| 794 | +Appendices: complete prompts and protocol versions; task cards and rubrics; evaluator validation; statistical details; capture methodology and gallery; model/environment records; intervention ledger; extra results; reproduction instructions. | ||||
| 795 | + | ||||
| 796 | +Aim for roughly 25–40 substantive main-text pages plus justified appendices if the work supports it. Page count is not an acceptance criterion. Do not inflate the text with repeated descriptions of autonomy. All figures must be discussed in the argument. Describe null results and failed tasks seriously. | ||||
| 797 | + | ||||
| 798 | +Use the actual UQO title-page and working-paper conventions. Verify author metadata. Use clear notation, numbered equations where useful, booktabs-style tables, linked references and legible figures. Write the abstract and final introduction after the main findings are verified. | ||||
| 799 | + | ||||
| 800 | +### 20.1 Claims that are not permitted without evidence | ||||
| 801 | + | ||||
| 802 | +- "Fully autonomous science" from a few successful task runs. | ||||
| 803 | +- "Independent reviewer" solely because a role prompt uses that word. | ||||
| 804 | +- "Novel scientific discovery" when the task reproduces a known answer. | ||||
| 805 | +- "Reproducible" when only archived responses were replayed. | ||||
| 806 | +- "Lower cost" when setup and reviewer compute were omitted. | ||||
| 807 | +- "Real-time data" when only a revised final-vintage dataset was used. | ||||
| 808 | +- "Authentic native screenshot" for a fabricated or reconstructed interface. | ||||
| 809 | +- "Human-level" or "better than researchers" without a valid human comparison. | ||||
| 810 | +- "All checks passed" without executed receipts and an appropriate scientific scope. | ||||
| 811 | + | ||||
| 812 | +## 21. Reproducibility and release modes | ||||
| 813 | + | ||||
| 814 | +Implement and distinguish three modes: | ||||
| 815 | + | ||||
| 816 | +1. Infrastructure tests: small fixtures and mocks that validate orchestration, schemas, gates and capture plumbing. They do not require provider access and do not generate scientific treatment-effect results. | ||||
| 817 | +2. Artifact replay: reconstruct the analysis, tables, figures and manuscript from recorded authorized outputs. This tests downstream reproducibility, not fresh model behavior. | ||||
| 818 | +3. Fresh live replication: launch new Claude Code sessions using the recorded task and treatment protocol, acknowledging provider stochasticity, model changes and access requirements. | ||||
| 819 | + | ||||
| 820 | +Provide real commands matching the implemented code. A possible command interface is make test, make smoke-live, make pilot, make main, make analyze, make paper, make replay, make validate-release; these names are proposals until implemented. Never claim they ran before actual execution. | ||||
| 821 | + | ||||
| 822 | +Pin the environment as far as practical; record operating system, architecture, client version, model metadata, tool versions and significant configuration. Store authorized raw traces and responses securely, and create a public subset where disclosure is permitted. | ||||
| 823 | + | ||||
| 824 | +Build a release manifest with file hashes, provenance, licensing notes and exclusions. Validate a clean replay of the headline analysis. Inspect the final PDF page by page for unreadable screenshots, clipped formulas, broken tables and unresolved references. The PDF must be nonempty, searchable and consistent with the saved results. | ||||
| 825 | + | ||||
| 826 | +## 22. Sequential execution phases and acceptance gates | ||||
| 827 | + | ||||
| 828 | +Phase 00 — Inspect identity, sources and environment | ||||
| 829 | + | ||||
| 830 | +Inspect the UQO index, WP29 collisions, existing files, source artifacts, current official documentation, Claude Code availability, auth status, resources and capture capabilities. Produce reports/environment_audit.md, a source inventory and a concrete gap list. | ||||
| 831 | + | ||||
| 832 | +Gate: project identity is protected; real capabilities and missing inputs are distinguished; no credentials are exposed. Continue feasible setup while any external blocker is resolved. | ||||
| 833 | + | ||||
| 834 | +Phase 01 — Literature and scientific blueprint | ||||
| 835 | + | ||||
| 836 | +Read primary prior work, code the source mandates, define the candidate contribution and write the smallest executable study blueprint. Establish scientific endpoints and competing explanations. | ||||
| 837 | + | ||||
| 838 | +Gate: closest prior work is identified; novelty claims are qualified; the study tests a method rather than assumes it works. | ||||
| 839 | + | ||||
| 840 | +Phase 02 — Protocol, task suite and evaluator specification | ||||
| 841 | + | ||||
| 842 | +Create treatment prompts, task cards, evaluator definitions, splits, budget plan, capture protocol, intervention categories and analysis plan. Design protected oracles and task-level assignment. | ||||
| 843 | + | ||||
| 844 | +Gate: scientific information is matched across arms; success/failure definitions are frozen for the pilot; hidden answers have an explicit protection plan; negative and infeasible cases are covered. | ||||
| 845 | + | ||||
| 846 | +Phase 03 — Implement the minimal harness | ||||
| 847 | + | ||||
| 848 | +Build task loading, isolation, genuine session launching, event storage, resource limits, output collection and deterministic evaluation. Use mocks only for infrastructure tests. Test successful and deliberately invalid artifacts. | ||||
| 849 | + | ||||
| 850 | +Gate: actual tests show the harness rejects known defects and preserves provenance; worker access to hidden evaluation material is prevented by tested controls. | ||||
| 851 | + | ||||
| 852 | +Phase 04 — Capture system and evidence viewer | ||||
| 853 | + | ||||
| 854 | +Implement actual screenshot capture and a small evidence viewer backed by the real database. Test event-triggered capture, hashes, redaction and caption metadata. Measure overhead consistently across arms. | ||||
| 855 | + | ||||
| 856 | +Gate: at least one genuine capture is linked to an actual test event; synthetic UI imagery is not used; public evidence contains no secrets. Mark infrastructure-only captures accordingly. | ||||
| 857 | + | ||||
| 858 | +Phase 05 — Real smoke experiment | ||||
| 859 | + | ||||
| 860 | +Run the four-arm smoke configuration using actual Claude Code inference on one development task, subject to available authorization and limits. Capture real sessions/events and independently grade the artifacts. | ||||
| 861 | + | ||||
| 862 | +Gate: four genuine task executions are accounted for, including failures; configuration isolation and treatment delivery are verified; the results are development observations, not confirmatory findings. | ||||
| 863 | + | ||||
| 864 | +Phase 06 — Development pilot and design freeze | ||||
| 865 | + | ||||
| 866 | +Run the development pilot, diagnose instrumentation and evaluator failures, measure costs and set the final affordable design. Perform task-cluster precision analysis. Freeze final tasks, prompts, thresholds, budgets, assignment, screenshot sampling and analysis code interfaces. | ||||
| 867 | + | ||||
| 868 | +Gate: dated protocol and hashes exist; amendments are traceable; pilot tasks do not contaminate the final set; the chosen scale is justified rather than assumed sufficient. | ||||
| 869 | + | ||||
| 870 | +Phase 07 — Main benchmark | ||||
| 871 | + | ||||
| 872 | +Execute the frozen assignments with balanced order and actual live sessions. Preserve every run, event, failure, intervention, artifact and required capture. Monitor limits without tuning the method on outcomes. | ||||
| 873 | + | ||||
| 874 | +Gate: the execution ledger reconciles with the frozen assignment; integrity and capture coverage are audited; completion counts are real and independently checked. | ||||
| 875 | + | ||||
| 876 | +Phase 08 — Transfer, recovery and selected ablations | ||||
| 877 | + | ||||
| 878 | +Run the separately specified mini-projects, controlled recovery tasks and prespecified ablations. Keep exploratory follow-ups separate. Capture before/failure/after evidence for recovery cases. | ||||
| 879 | + | ||||
| 880 | +Gate: experiments support their own stated scope; no synthetic event is mislabeled natural; new cases have not inherited prior answers. | ||||
| 881 | + | ||||
| 882 | +Phase 09 — Independent evaluation and statistical analysis | ||||
| 883 | + | ||||
| 884 | +Freeze submissions, execute final evaluators, conduct available authorized reviews, build the analysis dataset and estimate effects/uncertainty. Verify headline results from raw records and preserve adverse findings. | ||||
| 885 | + | ||||
| 886 | +Gate: scientific scoring is not mere self-report; uncertainty respects task dependence; exclusions and missingness are visible; tables and plots regenerate. | ||||
| 887 | + | ||||
| 888 | +Phase 10 — Manuscript and visual evidence appendix | ||||
| 889 | + | ||||
| 890 | +Write the complete article from the verified results. Include method algorithms, authentic screenshots with provenance, quantitative figures, tables, failure analysis and limitations. Finalize the title and abstract from what actually happened. | ||||
| 891 | + | ||||
| 892 | +Gate: every central claim is supported; screenshots are correctly classified; prose matches evidence and scope; bibliography is verified. | ||||
| 893 | + | ||||
| 894 | +Phase 11 — Adversarial scientific and systems review | ||||
| 895 | + | ||||
| 896 | +Run distinct reviews of experimental validity, scientific task correctness, evaluator leakage, systems isolation, cost accounting and manuscript claims. Record the actual identities and dependence of reviewers. Resolve objections with evidence and rerun affected checks where permitted. | ||||
| 897 | + | ||||
| 898 | +Gate: critical unresolved problems are corrected or the associated claims removed; review is not falsely labeled human or independent. | ||||
| 899 | + | ||||
| 900 | +Phase 12 — Reproduction, final build and delivery | ||||
| 901 | + | ||||
| 902 | +Replay the analysis in a clean documented environment; verify all deliverables; compile and inspect the PDF; package permitted artifacts and exact commands. Produce final status and limitations. | ||||
| 903 | + | ||||
| 904 | +Gate: actual research paper, live experiment evidence, authentic captures, generated results and a functioning replay package are delivered. A proposal or mock-only demonstration does not satisfy this gate. | ||||
| 905 | + | ||||
| 906 | +At every phase append to reports/phase_status.md: phase ID, timestamps, exact work performed, input versions, outputs, checks executed, failures, costs, interventions, unresolved scientific issues and next eligible action. An issue in one branch does not justify abandoning independent feasible work. | ||||
| 907 | + | ||||
| 908 | +## 23. Final acceptance rubric | ||||
| 909 | + | ||||
| 910 | +| Dimension | Required evidence | Unacceptable substitute | | ||||
| 911 | +|---|---|---| | ||||
| 912 | +| Method | Implemented contracts, state transitions, verification and recovery | A long prompt with no tested execution system | | ||||
| 913 | +| Live experimentation | Actual Claude Code invocations, traces and artifacts | Mock responses or an invented conversation | | ||||
| 914 | +| Fair comparison | Matched task facts/tools/budgets and controlled assignment | Extra answers or free reviewer compute in the preferred arm | | ||||
| 915 | +| Isolation | Tested context and oracle-access boundaries | A prompt requesting that the agent not look | | ||||
| 916 | +| Scientific evaluation | Valid rubrics, reference answers and transparent limitations | Executor self-grading alone | | ||||
| 917 | +| Screenshots | Authentic captured surfaces linked to runs and events | Generated UI artwork or unlabeled reconstructions | | ||||
| 918 | +| Statistics | Correct units, denominators, uncertainty and failure accounting | Treating repeated tool calls as independent samples | | ||||
| 919 | +| Autonomy | Actual intervention and preparation records | Assuming no humans because an agent was used | | ||||
| 920 | +| Reproducibility | Tested artifact replay and documented fresh-run procedure | An archive of code that has never rebuilt the results | | ||||
| 921 | +| Writing | Evidence-backed research argument and verified citations | A tutorial padded with hypothetical findings | | ||||
| 922 | + | ||||
| 923 | +If the authorized environment cannot meet one criterion, report the exact blocked dimension and deliver the strongest honest partial package. Do not declare full completion. Do not hide a failed hypothesis: the method's limitations may be the most useful scientific result. | ||||
| 924 | + | ||||
| 925 | +## 24. Final deliverables | ||||
| 926 | + | ||||
| 927 | +Create names consistent with the verified UQO series, including equivalents of: | ||||
| 928 | + | ||||
| 929 | +- WP29_Autonomous_Research_Claude_Code_Boucher.pdf | ||||
| 930 | +- full LaTeX source, bibliography and appendix; | ||||
| 931 | +- WP29_Method_and_Implementation.zip; | ||||
| 932 | +- frozen protocols, treatment prompts, task cards and assignment manifests; | ||||
| 933 | +- live-run registry and authorized traces; | ||||
| 934 | +- evaluator specification, validation and scoring outputs; | ||||
| 935 | +- WP29_Experiment_Results.csv and machine-readable detailed results; | ||||
| 936 | +- generated vector figures and LaTeX tables with producing scripts; | ||||
| 937 | +- WP29_Visual_Evidence_Appendix.pdf and a screenshot manifest; | ||||
| 938 | +- a shareable evidence gallery with authentic public-safe images; | ||||
| 939 | +- WP29_Reproducibility.md with actually tested replay commands; | ||||
| 940 | +- WP29_Limitations_and_Claims.md; | ||||
| 941 | +- WP29_Human_Interventions_and_Costs.csv; | ||||
| 942 | +- WP29_Final_Review.md; | ||||
| 943 | +- a concise research summary explaining the contribution, evidence and limitations. | ||||
| 944 | + | ||||
| 945 | +The final report must state: | ||||
| 946 | + | ||||
| 947 | +1. The research question and precise method contributed. | ||||
| 948 | +2. Which experiments were actually run, on which client/model versions. | ||||
| 949 | +3. Numbers of assigned tasks, live executions, completed evaluations and failures. | ||||
| 950 | +4. Main results with effect sizes, uncertainty and denominators. | ||||
| 951 | +5. What evidence supports or fails to support each principal hypothesis. | ||||
| 952 | +6. Human preparation/intervention/review and known resource costs. | ||||
| 953 | +7. Which screenshots are live native captures, live dashboard captures, archived viewers or replays. | ||||
| 954 | +8. What can be reproduced from saved artifacts and what requires fresh provider access. | ||||
| 955 | +9. Outstanding scientific limitations and the actual final validation status. | ||||
| 956 | +10. Exact paths to all deliverables. | ||||
| 957 | + | ||||
| 958 | +## 25. Start now | ||||
| 959 | + | ||||
| 960 | +Begin with the repository and environment audit, then build the smallest live, measurable experiment. Verify the source mandates and prior research. Implement the method and evaluation boundaries before spending resources on large runs. Carry out the experiments with actual Claude Code instances, preserve their real traces, take authentic screenshots, calculate the results, and write a rigorous English WP29 article. | ||||
| 961 | + | ||||
| 962 | +The objective is not to demonstrate that Claude can produce a persuasive paper about itself. The objective is to establish, through controlled and auditable evidence, what protocol-guided autonomous research can accomplish, when it fails, and what it costs. | ||||
added
protocol/amendments.csv
+1 −0
@@ -0,0 +1 @@ | |||||
| 1 | +amendment_id,timestamp_utc,phase,before_or_after_results,document,description,rationale,previous_version_ref | ||||
added
reports/environment_audit.md
+77 −0
@@ -0,0 +1,77 @@ | |||||
| 1 | +# Environment audit — WP29 (Phase 00) | ||||
| 2 | + | ||||
| 3 | +Audit performed 2026-10-29 (evening, America/Toronto) by the WP29 executor (Claude Code session, model `claude-fable-5-1`, client 2.1.314, operated by Simon-Pierre Boucher). No credential values were printed or copied into this repository. | ||||
| 4 | + | ||||
| 5 | +## 1. Project identity and collision check | ||||
| 6 | + | ||||
| 7 | +| Check | Result | | ||||
| 8 | +|---|---| | ||||
| 9 | +| Series index | `~/Desktop/Recherche-UQO/README.md` + `HARMONISATION.md`; highest number in use is **28** (`finance/distributed-mle-synchronization`, repo `wp28_uqo.git`). A second project (`finance/russell3000-strategic-project-database`) carries the FIRC label 0001 and is not numbered in the series. | | ||||
| 10 | +| WP29 collision | No directory, repository (`gitsrv:srv/git/wp29_uqo.git` absent — repositories end at `wp28_uqo.git`), index row or file named WP29 exists. **No collision.** | | ||||
| 11 | +| Chosen location | `~/Desktop/Recherche-UQO/methodes/autonomous-research-claude-code/` — a new third category *méthodes* (the paper is neither real estate nor finance). To be added as row 29 in the series index at packaging time. | | ||||
| 12 | +| Author metadata | Template `_modele-working-paper/main.tex`: author Simon-Pierre Boucher, Département des sciences administratives, Université du Québec en Outaouais, simon-pierre.boucher@uqo.ca, Pavillon Alexandre-Taché, 283 boul. Alexandre-Taché, Gatineau (Québec) J9A 1L8. Title page = `sections/titlepage.tex` with `uq_logo.jpg`, "Working Paper No.~N", date, version; abstract page with keywords and JEL. | | ||||
| 13 | + | ||||
| 14 | +## 2. Source artefacts | ||||
| 15 | + | ||||
| 16 | +| Artefact named in the mandate | Status | | ||||
| 17 | +|---|---| | ||||
| 18 | +| `Methode_recherche_autonome_CLAUDE.pdf` | **Not present** on this machine (Spotlight + `find` over `~/Desktop`, `~/Downloads`). | | ||||
| 19 | +| `Kit_recherche_autonome_CLAUDE.zip` | **Not present**. | | ||||
| 20 | +| `CLAUDE_WP_UQO_2026-10-29.zip` | **Not present**. | | ||||
| 21 | +| Primary mandates via `https://git.spboucher.ai/raw/...` | **Retrieved** 2026-10-29 ≈ 03:00 UTC: 11 distinct `CLAUDE.md` (WP15, WP18–WP26, WP28) + WP15 `PROMPT_INITIAL_CLAUDE.md` (byte-identical to WP15 `CLAUDE.md`, SHA-256 `2dd19c59…`) + WP27 `docs/DESIGN-BRIEF.md`. WP27 `CLAUDE.md` → HTTP 404. Hashes in `research/corpus_manifest.csv`, files in `research/corpus/`. | | ||||
| 22 | + | ||||
| 23 | +The three packaged artefacts were therefore reconstructed from the live endpoints, exactly as the mandate instructs when they are not mounted. No claim is made about their packaged contents. | ||||
| 24 | + | ||||
| 25 | +## 3. Claude Code client (laptop = builder/controller/evaluator host) | ||||
| 26 | + | ||||
| 27 | +| Item | Observed value | | ||||
| 28 | +|---|---| | ||||
| 29 | +| Host | MacBook (Apple silicon, arm64), macOS 27.0 (build 26A5425a); Node v25.9.0, npm 11.12.1 | | ||||
| 30 | +| `claude --version` | `2.1.314 (Claude Code)` — installed via npm global `@anthropic-ai/claude-code@2.1.314` | | ||||
| 31 | +| `claude auth status` | `loggedIn: true`, `authMethod: api_key`, `apiProvider: firstParty`, org "AgentiLab". Keychain item `Claude Code-credentials` present. No `ANTHROPIC_API_KEY` in the interactive environment. | | ||||
| 32 | +| User-level instructions | `~/.claude/CLAUDE.md` exists (large cluster-operations file). `~/.claude/settings.json`: model `fable[1m]`, one `PreToolUse` hook (auto-approve), 3 LSP plugins, `fastMode: true`. `~/.claude.json` configures 9 MCP servers (apify, tavily, worldbank, openalex, anthropic, polymarket, etherscan, notion, hfmarketdata). 121 project directories under `~/.claude/projects` (auto-memory). | | ||||
| 33 | +| Official docs | `memory`, `headless`, `cli-reference`, `hooks`, `permissions` fetched 2026-10-29 (markdown, `docs/claude-code-docs/`, retrieval timestamp in `retrieved_utc.txt`). | | ||||
| 34 | + | ||||
| 35 | +### 3.1 Verified flags relevant to the design (from `claude --help` 2.1.314 and `cli-reference.md`) | ||||
| 36 | + | ||||
| 37 | +`-p/--print`, `--output-format text|json|stream-json`, `--include-partial-messages`, `--verbose`, `--bare`, `--system-prompt[-file]`, `--append-system-prompt[-file]`, `--tools <list>` (restrict built-in tool set), `--allowedTools`, `--disallowedTools`, `--permission-mode`, `--permission-prompts host|none`, `--max-budget-usd` (print mode; client-side estimate; subagent spend counts; spend can slightly exceed the cap), `--max-turns`, `--resume <session-id|path>`, `--session-id <uuid>`, `--fork-session`, `--no-session-persistence`, `--model`, `--effort`, `--setting-sources`, `--settings`, `--strict-mcp-config`, `--add-dir`, `--restricted`. **No temperature or random-seed flag exists** (none will be simulated). `--json-schema` exists for structured final output. | ||||
| 38 | + | ||||
| 39 | +### 3.2 Behaviours verified by live probes (2026-10-29) | ||||
| 40 | + | ||||
| 41 | +| Probe | Observation | | ||||
| 42 | +|---|---| | ||||
| 43 | +| `claude --bare -p "Reply with exactly OK" --model claude-opus-5-5 --output-format json --tools "" --max-budget-usd 0.10` with `ANTHROPIC_API_KEY` exported | Success in 1.55 s; `result: "OK"`, `total_cost_usd: 0.0004`, `modelUsage` reports `canonicalModel: claude-opus-5-5`, `costBasis: list`, context window 1,000,000, 80 input / 4 output tokens, `session_id` returned. | | ||||
| 44 | +| Sentinel test, **normal** `-p` mode in a temp dir with a project `CLAUDE.md` containing `SENTINEL-7731` (model `claude-haiku-5-5`, tools disabled) | Model reported `SENTINEL-7731` **and** cluster node aliases from `~/.claude/CLAUDE.md`; first-turn input ≈ **49,077 tokens**. Confirms that non-bare print mode loads user-level and project instructions (and the hook/MCP configuration) — unsuitable for controlled arms. | | ||||
| 45 | +| Sentinel test, `--bare -p`, same directory | Model reported `NONE` for both; first-turn input **144 tokens**. Confirms `--bare` skips `CLAUDE.md` auto-discovery, auto-memory, hooks, plugins and MCP. | | ||||
| 46 | +| `--bare -p --append-system-prompt-file append.txt` (sentinel `APPEND-4420`) | Model reported `APPEND-4420`; input 171 tokens. Confirms that explicit instruction injection works in bare mode and is the mechanism used to deliver treatment protocols. | | ||||
| 47 | +| Bare mode authentication | `--bare` ignores OAuth/keychain and requires `ANTHROPIC_API_KEY` (verified in help text and docs). The study uses the researcher's existing first-party API key (sourced at launch time from an existing project `.env`, never written to this repository or to run logs). | | ||||
| 48 | + | ||||
| 49 | +## 4. Executor hosts (cluster nodes) and isolation boundary | ||||
| 50 | + | ||||
| 51 | +| Node | Hardware | Claude Code | Python env | | ||||
| 52 | +|---|---|---|---| | ||||
| 53 | +| M3U96a | Mac Studio M3 Ultra, 28 cores reported by `nproc`, 96 GB, macOS 26.6 | upgraded 2.1.204 → **2.1.314** | `~/wp29/venv` (Python 3.14.5): numpy 2.3.4, pandas 2.3.3, scipy 1.16.2, statsmodels 0.14.5, matplotlib 3.10.7 | | ||||
| 54 | +| M3U96b | Mac Studio M3 Ultra, 28 cores, 96 GB | **2.1.314** | same pinned venv | | ||||
| 55 | +| M4M64a | Mac Studio M4 Max, 16 cores, 64 GB | **2.1.314** | same pinned venv | | ||||
| 56 | +| M4M64b | Mac Studio M4 Max, 16 cores, 64 GB | **2.1.314** | same pinned venv | | ||||
| 57 | + | ||||
| 58 | +Boundary facts: (i) the nodes hold no copy of this repository, of the oracles, or of the series; (ii) from M3U96a, TCP port 22 of the laptop (192.168.2.184) is **not reachable** (`nc -z` → no), so an executor process on a node cannot reach the evaluator host by SSH; (iii) each node has a `~/.claude/CLAUDE.md` (cluster file) which `--bare` does not load (verified on the laptop; to be re-verified per node with the sentinel probe in the isolation tests, Phase 03); (iv) `claude --bare -p` on M3U96a with the key passed in the SSH command environment returned `OK` (cost 0.00096 USD, model claude-haiku-5-5), establishing that live inference from the nodes works. | ||||
| 59 | + | ||||
| 60 | +## 5. Capture capabilities | ||||
| 61 | + | ||||
| 62 | +| Tool | Status | | ||||
| 63 | +|---|---| | ||||
| 64 | +| `/usr/sbin/screencapture` | Available (native window/screen capture; `-l <windowid>` for a specific window, `-x` silent). | | ||||
| 65 | +| Safari | Available (for dashboard captures via AppleScript/`screencapture`). | | ||||
| 66 | +| Chromium | Wrapper present but application missing (`/Applications/Chromium.app` absent) — not usable. | | ||||
| 67 | +| `script` (BSD) | Available for terminal session recording (transcript replay mode only). | | ||||
| 68 | +| tmux / asciinema | Not installed. | | ||||
| 69 | + | ||||
| 70 | +## 6. Gap list (Phase 00) | ||||
| 71 | + | ||||
| 72 | +1. Packaged source artefacts absent → replaced by live retrieval with hashes (done). | ||||
| 73 | +2. No human second coder, no external human reviewers available → corpus coding single-coder; human-review cells will be labelled unavailable. | ||||
| 74 | +3. Chromium absent → evidence-viewer screenshots will use Safari or native `screencapture`. | ||||
| 75 | +4. Budget: no explicit monetary budget was stated in the mandate. A provisional live-inference envelope is set by the executor and recorded in `protocol/amendments.csv` (see Phase 02); the pilot measures real costs before the confirmatory design is frozen. | ||||
| 76 | +5. Model stochasticity cannot be seeded (no seed flag) → repeats are genuine fresh sessions. | ||||
| 77 | +6. `--max-budget-usd` is a client-side estimate that can be slightly exceeded → the harness records both the cap and the observed `total_cost_usd`. | ||||
added
reports/interventions.csv
+2 −0
@@ -0,0 +1,2 @@ | |||||
| 1 | +intervention_id,timestamp_utc,actor,phase_or_run,category,description,duration_minutes,measurement_basis,scientific_impact | ||||
| 2 | +I-001,2026-10-29T02:38:00Z,researcher (S.-P. Boucher),Phase 00,preparation,"Prepared the WP29 mandate (CLAUDE.md text) outside the session and pasted it into a Claude Code session with the instruction 'fait ce projet de recherche'.",unknown,not measured (historical preparation time unknown),Defines the entire study scope; all design decisions derive from it. | ||||
added
reports/phase_status.md
+16 −0
@@ -0,0 +1,16 @@ | |||||
| 1 | +# Phase status — WP29 | ||||
| 2 | + | ||||
| 3 | +Append-only log. Times are UTC unless stated. "Executor" = the Claude Code session (claude-fable-5-1, client 2.1.314) operated by S.-P. Boucher. | ||||
| 4 | + | ||||
| 5 | +## Phase 00 — Inspect identity, sources and environment | ||||
| 6 | + | ||||
| 7 | +- **Started** 2026-10-29 ≈ 02:40 UTC (2026-10-29 22:40 local). **Closed** 2026-10-29 ≈ 03:30 UTC. | ||||
| 8 | +- **Work performed**: read series index (`Recherche-UQO/README.md`, `HARMONISATION.md`) → no WP29 collision; created repository skeleton; preserved the full mandate verbatim in `protocol/WP29_FULL_MANDATE.md`; retrieved 13 corpus files with SHA-256 (`research/corpus_manifest.csv`); downloaded 5 official Claude Code doc pages; probed `claude --version/--help/auth status`; ran 4 live sentinel/capability probes (laptop, bare vs normal mode, append-system-prompt, node M3U96a); aligned 4 executor nodes to client 2.1.314 + pinned Python venv; wrote `reports/environment_audit.md`. | ||||
| 9 | +- **Inputs**: mandate pasted by the researcher (2026-10-29); client 2.1.314; docs retrieved 2026-10-29. | ||||
| 10 | +- **Outputs**: `reports/environment_audit.md`, `research/corpus_manifest.csv`, `research/corpus/*`, `docs/claude-code-docs/*`, `protocol/WP29_FULL_MANDATE.md`. | ||||
| 11 | +- **Checks executed**: HTTP status + hash per corpus file; bare-mode sentinel probes (pass: bare loads 144 tokens, normal mode 49k tokens incl. user CLAUDE.md); node→laptop SSH unreachable (boundary holds). | ||||
| 12 | +- **Costs**: probes ≈ 0.0016 USD of API inference (haiku/opus probes); no human minutes measured beyond the pasting of the mandate. | ||||
| 13 | +- **Interventions**: see `reports/interventions.csv` (I-001: mandate preparation and pasting by the researcher, duration unknown). | ||||
| 14 | +- **Unresolved**: packaged artefacts absent (replaced by live retrieval); budget envelope set provisionally by the executor (Phase 02). | ||||
| 15 | +- **Gate**: identity protected ✔; capabilities vs missing inputs distinguished ✔; no credentials exposed ✔. **PASSED.** | ||||
| 16 | +- **Next eligible**: Phase 01 (literature + corpus coding, launched as two background subagents at ≈ 03:25 UTC) and Phase 02 (protocol, tasks, evaluators) in parallel. | ||||
added
research/arxiv_seed.xml
+165 −0
@@ -0,0 +1,165 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/ttPaYvImU7mSRia0id58PCFWnIg</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2504.08066,2501.04227,2410.05080&start=0&max_results=3</title> | ||||
| 5 | + <updated>2026-10-30T03:04:25Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=3&id_list=2504.08066,2501.04227,2410.05080" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>3</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>3</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2504.08066v1</id> | ||||
| 12 | + <title>The AI Scientist-v2: Workshop-Level Automated Scientific Discovery via Agentic Tree Search</title> | ||||
| 13 | + <updated>2025-04-10T18:44:41Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2504.08066v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2504.08066v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>AI is increasingly playing a pivotal role in transforming how scientific discoveries are made. We introduce The AI Scientist-v2, an end-to-end agentic system capable of producing the first entirely AI generated peer-review-accepted workshop paper. This system iteratively formulates scientific hypotheses, designs and executes experiments, analyzes and visualizes data, and autonomously authors scientific manuscripts. Compared to its predecessor (v1, Lu et al., 2024 arXiv:2408.06292), The AI Scientist-v2 eliminates the reliance on human-authored code templates, generalizes effectively across diverse machine learning domains, and leverages a novel progressive agentic tree-search methodology managed by a dedicated experiment manager agent. Additionally, we enhance the AI reviewer component by integrating a Vision-Language Model (VLM) feedback loop for iterative refinement of content and aesthetics of the figures. We evaluated The AI Scientist-v2 by submitting three fully autonomous manuscripts to a peer-reviewed ICLR workshop. Notably, one manuscript achieved high enough scores to exceed the average human acceptance threshold, marking the first instance of a fully AI-generated paper successfully navigating a peer review. This accomplishment highlights the growing capability of AI in conducting all aspects of scientific research. We anticipate that further advancements in autonomous scientific discovery technologies will profoundly impact human knowledge generation, enabling unprecedented scalability in research productivity and significantly accelerating scientific breakthroughs, greatly benefiting society at large. We have open-sourced the code at https://github.com/SakanaAI/AI-Scientist-v2 to foster the future development of this transformative technology. We also discuss the role of AI in science, including AI safety.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2025-04-10T18:44:41Z</published> | ||||
| 21 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Yutaro Yamada</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Robert Tjarko Lange</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Cong Lu</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Shengran Hu</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Chris Lu</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>Jakob Foerster</name> | ||||
| 39 | + </author> | ||||
| 40 | + <author> | ||||
| 41 | + <name>Jeff Clune</name> | ||||
| 42 | + </author> | ||||
| 43 | + <author> | ||||
| 44 | + <name>David Ha</name> | ||||
| 45 | + </author> | ||||
| 46 | + </entry> | ||||
| 47 | + <entry> | ||||
| 48 | + <id>http://arxiv.org/abs/2501.04227v2</id> | ||||
| 49 | + <title>Agent Laboratory: Using LLM Agents as Research Assistants</title> | ||||
| 50 | + <updated>2025-06-17T16:19:14Z</updated> | ||||
| 51 | + <link href="https://arxiv.org/abs/2501.04227v2" rel="alternate" type="text/html"/> | ||||
| 52 | + <link href="https://arxiv.org/pdf/2501.04227v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 53 | + <summary>Historically, scientific discovery has been a lengthy and costly process, demanding substantial time and resources from initial conception to final results. To accelerate scientific discovery, reduce research costs, and improve research quality, we introduce Agent Laboratory, an autonomous LLM-based framework capable of completing the entire research process. This framework accepts a human-provided research idea and progresses through three stages--literature review, experimentation, and report writing to produce comprehensive research outputs, including a code repository and a research report, while enabling users to provide feedback and guidance at each stage. We deploy Agent Laboratory with various state-of-the-art LLMs and invite multiple researchers to assess its quality by participating in a survey, providing human feedback to guide the research process, and then evaluate the final paper. We found that: (1) Agent Laboratory driven by o1-preview generates the best research outcomes; (2) The generated machine learning code is able to achieve state-of-the-art performance compared to existing methods; (3) Human involvement, providing feedback at each stage, significantly improves the overall quality of research; (4) Agent Laboratory significantly reduces research expenses, achieving an 84% decrease compared to previous autonomous research methods. We hope Agent Laboratory enables researchers to allocate more effort toward creative ideation rather than low-level coding and writing, ultimately accelerating scientific discovery.</summary> | ||||
| 54 | + <category term="cs.HC" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 55 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 56 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 57 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 58 | + <published>2025-01-08T01:58:42Z</published> | ||||
| 59 | + <arxiv:primary_category term="cs.HC"/> | ||||
| 60 | + <author> | ||||
| 61 | + <name>Samuel Schmidgall</name> | ||||
| 62 | + </author> | ||||
| 63 | + <author> | ||||
| 64 | + <name>Yusheng Su</name> | ||||
| 65 | + </author> | ||||
| 66 | + <author> | ||||
| 67 | + <name>Ze Wang</name> | ||||
| 68 | + </author> | ||||
| 69 | + <author> | ||||
| 70 | + <name>Ximeng Sun</name> | ||||
| 71 | + </author> | ||||
| 72 | + <author> | ||||
| 73 | + <name>Jialian Wu</name> | ||||
| 74 | + </author> | ||||
| 75 | + <author> | ||||
| 76 | + <name>Xiaodong Yu</name> | ||||
| 77 | + </author> | ||||
| 78 | + <author> | ||||
| 79 | + <name>Jiang Liu</name> | ||||
| 80 | + </author> | ||||
| 81 | + <author> | ||||
| 82 | + <name>Michael Moor</name> | ||||
| 83 | + </author> | ||||
| 84 | + <author> | ||||
| 85 | + <name>Zicheng Liu</name> | ||||
| 86 | + </author> | ||||
| 87 | + <author> | ||||
| 88 | + <name>Emad Barsoum</name> | ||||
| 89 | + </author> | ||||
| 90 | + </entry> | ||||
| 91 | + <entry> | ||||
| 92 | + <id>http://arxiv.org/abs/2410.05080v3</id> | ||||
| 93 | + <title>ScienceAgentBench: Toward Rigorous Assessment of Language Agents for Data-Driven Scientific Discovery</title> | ||||
| 94 | + <updated>2025-03-31T14:39:44Z</updated> | ||||
| 95 | + <link href="https://arxiv.org/abs/2410.05080v3" rel="alternate" type="text/html"/> | ||||
| 96 | + <link href="https://arxiv.org/pdf/2410.05080v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 97 | + <summary>The advancements of large language models (LLMs) have piqued growing interest in developing LLM-based language agents to automate scientific discovery end-to-end, which has sparked both excitement and skepticism about their true capabilities. In this work, we call for rigorous assessment of agents on individual tasks in a scientific workflow before making bold claims on end-to-end automation. To this end, we present ScienceAgentBench, a new benchmark for evaluating language agents for data-driven scientific discovery. To ensure the scientific authenticity and real-world relevance of our benchmark, we extract 102 tasks from 44 peer-reviewed publications in four disciplines and engage nine subject matter experts to validate them. We unify the target output for every task to a self-contained Python program file and employ an array of evaluation metrics to examine the generated programs, execution results, and costs. Each task goes through multiple rounds of manual validation by annotators and subject matter experts to ensure its annotation quality and scientific plausibility. We also propose two effective strategies to mitigate data contamination concerns. Using ScienceAgentBench, we evaluate five open-weight and proprietary LLMs, each with three frameworks: direct prompting, OpenHands CodeAct, and self-debug. Given three attempts for each task, the best-performing agent can only solve 32.4% of the tasks independently and 34.3% with expert-provided knowledge. In addition, we evaluate OpenAI o1-preview with direct prompting and self-debug, which can boost the performance to 42.2%, demonstrating the effectiveness of increasing inference-time compute but with more than 10 times the cost of other LLMs. Still, our results underscore the limitations of current language agents in generating code for data-driven discovery, let alone end-to-end automation for scientific research.</summary> | ||||
| 98 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 99 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 100 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 101 | + <published>2024-10-07T14:33:50Z</published> | ||||
| 102 | + <arxiv:comment>ICLR 2025. 60 pages</arxiv:comment> | ||||
| 103 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 104 | + <author> | ||||
| 105 | + <name>Ziru Chen</name> | ||||
| 106 | + </author> | ||||
| 107 | + <author> | ||||
| 108 | + <name>Shijie Chen</name> | ||||
| 109 | + </author> | ||||
| 110 | + <author> | ||||
| 111 | + <name>Yuting Ning</name> | ||||
| 112 | + </author> | ||||
| 113 | + <author> | ||||
| 114 | + <name>Qianheng Zhang</name> | ||||
| 115 | + </author> | ||||
| 116 | + <author> | ||||
| 117 | + <name>Boshi Wang</name> | ||||
| 118 | + </author> | ||||
| 119 | + <author> | ||||
| 120 | + <name>Botao Yu</name> | ||||
| 121 | + </author> | ||||
| 122 | + <author> | ||||
| 123 | + <name>Yifei Li</name> | ||||
| 124 | + </author> | ||||
| 125 | + <author> | ||||
| 126 | + <name>Zeyi Liao</name> | ||||
| 127 | + </author> | ||||
| 128 | + <author> | ||||
| 129 | + <name>Chen Wei</name> | ||||
| 130 | + </author> | ||||
| 131 | + <author> | ||||
| 132 | + <name>Zitong Lu</name> | ||||
| 133 | + </author> | ||||
| 134 | + <author> | ||||
| 135 | + <name>Vishal Dey</name> | ||||
| 136 | + </author> | ||||
| 137 | + <author> | ||||
| 138 | + <name>Mingyi Xue</name> | ||||
| 139 | + </author> | ||||
| 140 | + <author> | ||||
| 141 | + <name>Frazier N. Baker</name> | ||||
| 142 | + </author> | ||||
| 143 | + <author> | ||||
| 144 | + <name>Benjamin Burns</name> | ||||
| 145 | + </author> | ||||
| 146 | + <author> | ||||
| 147 | + <name>Daniel Adu-Ampratwum</name> | ||||
| 148 | + </author> | ||||
| 149 | + <author> | ||||
| 150 | + <name>Xuhui Huang</name> | ||||
| 151 | + </author> | ||||
| 152 | + <author> | ||||
| 153 | + <name>Xia Ning</name> | ||||
| 154 | + </author> | ||||
| 155 | + <author> | ||||
| 156 | + <name>Song Gao</name> | ||||
| 157 | + </author> | ||||
| 158 | + <author> | ||||
| 159 | + <name>Yu Su</name> | ||||
| 160 | + </author> | ||||
| 161 | + <author> | ||||
| 162 | + <name>Huan Sun</name> | ||||
| 163 | + </author> | ||||
| 164 | + </entry> | ||||
| 165 | +</feed> | ||||
added
research/corpus/WP15_CLAUDE.md
+2165 −0
@@ -0,0 +1,2165 @@ | |||||
| 1 | +# CLAUDE.md — Intraday Market Fragility Research Program | ||||
| 2 | + | ||||
| 3 | +## 0. Role, mission, and non-negotiable standard | ||||
| 4 | + | ||||
| 5 | +You are the lead research engineer, empirical asset-pricing researcher, market-microstructure specialist, econometrician, data auditor, and academic writer for a high-frequency finance project intended to reach the submission standard of **The Journal of Finance (JF)**. | ||||
| 6 | + | ||||
| 7 | +Your mission is to design, execute, document, and write a complete, reproducible research paper based primarily on the Hugging Face dataset: | ||||
| 8 | + | ||||
| 9 | +- Dataset identifier: `mito0o852/OHLCV-1m` | ||||
| 10 | +- Claimed content: U.S. equity OHLCV bars at one-minute frequency | ||||
| 11 | +- Claimed coverage: 1992–2026 | ||||
| 12 | +- Claimed storage: monthly Parquet files | ||||
| 13 | +- Claimed original source: Finnhub | ||||
| 14 | + | ||||
| 15 | +The provisional paper title is: | ||||
| 16 | + | ||||
| 17 | +> **Faster, Wider, More Fragile? The Evolution of Intraday Shock Propagation in U.S. Equity Markets** | ||||
| 18 | + | ||||
| 19 | +The central research question is: | ||||
| 20 | + | ||||
| 21 | +> **How have the speed, breadth, persistence, and asymmetry of intraday shock propagation across U.S. equities evolved over the past three decades, and under which market conditions does an initially idiosyncratic shock become sectoral or market-wide?** | ||||
| 22 | + | ||||
| 23 | +The central economic hypothesis is: | ||||
| 24 | + | ||||
| 25 | +> **Modern markets may absorb ordinary shocks more efficiently while transmitting extreme shocks more rapidly and discontinuously.** | ||||
| 26 | + | ||||
| 27 | +This is not a generic machine-learning forecasting project. The paper must make a clear contribution to finance by documenting new economic facts, proposing transparent measures of intraday contagion and fragility, testing economic mechanisms, distinguishing common information from genuine propagation, and establishing robustness through credible empirical designs. | ||||
| 28 | + | ||||
| 29 | +The final output must be: | ||||
| 30 | + | ||||
| 31 | +1. fully reproducible; | ||||
| 32 | +2. empirically honest; | ||||
| 33 | +3. economically motivated; | ||||
| 34 | +4. methodologically rigorous; | ||||
| 35 | +5. written in polished academic English; | ||||
| 36 | +6. formatted as a complete LaTeX submission package; | ||||
| 37 | +7. accompanied by a detailed Internet Appendix; | ||||
| 38 | +8. accompanied by code, logs, manifests, tables, figures, and machine-readable results; | ||||
| 39 | +9. prepared to the standard expected in a top finance journal; | ||||
| 40 | +10. explicit about every limitation imposed by OHLCV data. | ||||
| 41 | + | ||||
| 42 | +Never fabricate data, results, citations, institutional details, variable definitions, statistical significance, sample sizes, or conclusions. Never write a result in the paper before it has been generated and verified from a saved machine-readable output. | ||||
| 43 | + | ||||
| 44 | +--- | ||||
| 45 | + | ||||
| 46 | +# 1. Research philosophy | ||||
| 47 | + | ||||
| 48 | +## 1.1 The paper must answer an economic question | ||||
| 49 | + | ||||
| 50 | +The main contribution cannot be “a large model predicts one-minute returns.” Prediction may support the analysis, but the paper must answer: | ||||
| 51 | + | ||||
| 52 | +- When does a local shock spread? | ||||
| 53 | +- How rapidly does it spread? | ||||
| 54 | +- How broadly does it spread? | ||||
| 55 | +- How persistent is the propagation? | ||||
| 56 | +- Is propagation asymmetric for negative and positive shocks? | ||||
| 57 | +- Has propagation changed over time? | ||||
| 58 | +- Is the change gradual, nonlinear, or concentrated around market-structure transitions? | ||||
| 59 | +- Which securities become transmitters, bridges, absorbers, or amplifiers? | ||||
| 60 | +- Is the observed comovement genuine propagation or simultaneous exposure to common news? | ||||
| 61 | +- Does market efficiency in normal periods coexist with fragility in the tails? | ||||
| 62 | + | ||||
| 63 | +## 1.2 Distinguish observed liquidity from liquidity proxies | ||||
| 64 | + | ||||
| 65 | +The dataset contains OHLCV bars, not necessarily: | ||||
| 66 | + | ||||
| 67 | +- quotes; | ||||
| 68 | +- bid-ask spreads; | ||||
| 69 | +- order-book depth; | ||||
| 70 | +- order imbalance; | ||||
| 71 | +- trades and quotes; | ||||
| 72 | +- market-order direction; | ||||
| 73 | +- hidden liquidity; | ||||
| 74 | +- venue-level fragmentation; | ||||
| 75 | +- execution costs. | ||||
| 76 | + | ||||
| 77 | +Therefore: | ||||
| 78 | + | ||||
| 79 | +- Do not claim to observe liquidity directly. | ||||
| 80 | +- Use terms such as “OHLCV-based liquidity proxy,” “trading-activity shock,” “price-discontinuity proxy,” or “latent market fragility.” | ||||
| 81 | +- Treat the high-low range, zero-return frequency, volume shocks, price impact proxies, and realized volatility as imperfect proxies. | ||||
| 82 | +- Include a dedicated limitations section. | ||||
| 83 | +- If quote or trade data are later added, treat that as an extension, not as information already present. | ||||
| 84 | + | ||||
| 85 | +## 1.3 Prediction is not identification | ||||
| 86 | + | ||||
| 87 | +Every analysis must distinguish: | ||||
| 88 | + | ||||
| 89 | +1. contemporaneous co-movement; | ||||
| 90 | +2. predictive lead-lag; | ||||
| 91 | +3. propagation conditional on observed information; | ||||
| 92 | +4. causal propagation; | ||||
| 93 | +5. structural counterfactual simulation. | ||||
| 94 | + | ||||
| 95 | +Do not use causal language unless the design supports it. Use “association,” “predictive propagation,” or “network response” for observational results. Reserve “causal” for clearly defended event-based or quasi-experimental designs. | ||||
| 96 | + | ||||
| 97 | +--- | ||||
| 98 | + | ||||
| 99 | +# 2. Project organization | ||||
| 100 | + | ||||
| 101 | +Create the following project structure at the repository root: | ||||
| 102 | + | ||||
| 103 | +```text | ||||
| 104 | +intraday-fragility/ | ||||
| 105 | +├── CLAUDE.md | ||||
| 106 | +├── README.md | ||||
| 107 | +├── LICENSE | ||||
| 108 | +├── CITATION.cff | ||||
| 109 | +├── pyproject.toml | ||||
| 110 | +├── uv.lock | ||||
| 111 | +├── environment.yml | ||||
| 112 | +├── .env.example | ||||
| 113 | +├── .gitignore | ||||
| 114 | +├── Makefile | ||||
| 115 | +├── config/ | ||||
| 116 | +│ ├── base.yaml | ||||
| 117 | +│ ├── paths.yaml | ||||
| 118 | +│ ├── sample_filters.yaml | ||||
| 119 | +│ ├── shock_definitions.yaml | ||||
| 120 | +│ ├── models.yaml | ||||
| 121 | +│ ├── figures.yaml | ||||
| 122 | +│ └── tables.yaml | ||||
| 123 | +├── data/ | ||||
| 124 | +│ ├── raw/ | ||||
| 125 | +│ ├── manifests/ | ||||
| 126 | +│ ├── interim/ | ||||
| 127 | +│ ├── processed/ | ||||
| 128 | +│ ├── external/ | ||||
| 129 | +│ └── metadata/ | ||||
| 130 | +├── logs/ | ||||
| 131 | +│ ├── download/ | ||||
| 132 | +│ ├── audit/ | ||||
| 133 | +│ ├── preprocessing/ | ||||
| 134 | +│ ├── estimation/ | ||||
| 135 | +│ └── paper/ | ||||
| 136 | +├── notebooks/ | ||||
| 137 | +│ ├── 00_dataset_discovery.ipynb | ||||
| 138 | +│ ├── 01_small_sample_audit.ipynb | ||||
| 139 | +│ ├── 02_intraday_patterns.ipynb | ||||
| 140 | +│ └── 03_prototype_results.ipynb | ||||
| 141 | +├── src/ | ||||
| 142 | +│ └── intraday_fragility/ | ||||
| 143 | +│ ├── __init__.py | ||||
| 144 | +│ ├── cli.py | ||||
| 145 | +│ ├── paths.py | ||||
| 146 | +│ ├── logging_utils.py | ||||
| 147 | +│ ├── download.py | ||||
| 148 | +│ ├── manifest.py | ||||
| 149 | +│ ├── schema.py | ||||
| 150 | +│ ├── calendars.py | ||||
| 151 | +│ ├── corporate_actions.py | ||||
| 152 | +│ ├── identifiers.py | ||||
| 153 | +│ ├── universe.py | ||||
| 154 | +│ ├── cleaning.py | ||||
| 155 | +│ ├── features.py | ||||
| 156 | +│ ├── shocks.py | ||||
| 157 | +│ ├── networks.py | ||||
| 158 | +│ ├── contagion.py | ||||
| 159 | +│ ├── econometrics.py | ||||
| 160 | +│ ├── inference.py | ||||
| 161 | +│ ├── robustness.py | ||||
| 162 | +│ ├── simulations.py | ||||
| 163 | +│ ├── figures.py | ||||
| 164 | +│ ├── tables.py | ||||
| 165 | +│ ├── latex.py | ||||
| 166 | +│ └── validation.py | ||||
| 167 | +├── scripts/ | ||||
| 168 | +│ ├── 00_probe_hf_dataset.py | ||||
| 169 | +│ ├── 01_download_hf_data.py | ||||
| 170 | +│ ├── 02_build_raw_manifest.py | ||||
| 171 | +│ ├── 03_audit_schema.py | ||||
| 172 | +│ ├── 04_audit_market_calendar.py | ||||
| 173 | +│ ├── 05_audit_prices_and_volume.py | ||||
| 174 | +│ ├── 06_detect_corporate_actions.py | ||||
| 175 | +│ ├── 07_construct_security_master.py | ||||
| 176 | +│ ├── 08_build_clean_minute_panel.py | ||||
| 177 | +│ ├── 09_build_daily_metadata.py | ||||
| 178 | +│ ├── 10_construct_features.py | ||||
| 179 | +│ ├── 11_detect_shocks.py | ||||
| 180 | +│ ├── 12_estimate_networks.py | ||||
| 181 | +│ ├── 13_measure_propagation.py | ||||
| 182 | +│ ├── 14_run_baseline_regressions.py | ||||
| 183 | +│ ├── 15_run_event_studies.py | ||||
| 184 | +│ ├── 16_run_robustness.py | ||||
| 185 | +│ ├── 17_run_placebos.py | ||||
| 186 | +│ ├── 18_build_figures.py | ||||
| 187 | +│ ├── 19_build_tables.py | ||||
| 188 | +│ ├── 20_compile_paper.py | ||||
| 189 | +│ └── 21_validate_release.py | ||||
| 190 | +├── tests/ | ||||
| 191 | +│ ├── test_schema.py | ||||
| 192 | +│ ├── test_calendars.py | ||||
| 193 | +│ ├── test_cleaning.py | ||||
| 194 | +│ ├── test_features.py | ||||
| 195 | +│ ├── test_shocks.py | ||||
| 196 | +│ ├── test_networks.py | ||||
| 197 | +│ ├── test_econometrics.py | ||||
| 198 | +│ └── test_tables.py | ||||
| 199 | +├── outputs/ | ||||
| 200 | +│ ├── diagnostics/ | ||||
| 201 | +│ ├── estimates/ | ||||
| 202 | +│ ├── figures/ | ||||
| 203 | +│ ├── tables/ | ||||
| 204 | +│ ├── models/ | ||||
| 205 | +│ └── release/ | ||||
| 206 | +├── paper/ | ||||
| 207 | +│ ├── main.tex | ||||
| 208 | +│ ├── preamble.tex | ||||
| 209 | +│ ├── title_page.tex | ||||
| 210 | +│ ├── abstract.tex | ||||
| 211 | +│ ├── sections/ | ||||
| 212 | +│ │ ├── 01_introduction.tex | ||||
| 213 | +│ │ ├── 02_literature.tex | ||||
| 214 | +│ │ ├── 03_data.tex | ||||
| 215 | +│ │ ├── 04_measurement.tex | ||||
| 216 | +│ │ ├── 05_empirical_design.tex | ||||
| 217 | +│ │ ├── 06_results.tex | ||||
| 218 | +│ │ ├── 07_mechanisms.tex | ||||
| 219 | +│ │ ├── 08_robustness.tex | ||||
| 220 | +│ │ └── 09_conclusion.tex | ||||
| 221 | +│ ├── tables/ | ||||
| 222 | +│ ├── figures/ | ||||
| 223 | +│ ├── bibliography/ | ||||
| 224 | +│ │ └── references.bib | ||||
| 225 | +│ └── styles/ | ||||
| 226 | +├── appendix/ | ||||
| 227 | +│ ├── internet_appendix.tex | ||||
| 228 | +│ ├── sections/ | ||||
| 229 | +│ ├── tables/ | ||||
| 230 | +│ └── figures/ | ||||
| 231 | +└── docs/ | ||||
| 232 | + ├── DATA_DICTIONARY.md | ||||
| 233 | + ├── DATA_AUDIT.md | ||||
| 234 | + ├── EMPIRICAL_DESIGN.md | ||||
| 235 | + ├── LITERATURE_MAP.md | ||||
| 236 | + ├── REPRODUCIBILITY.md | ||||
| 237 | + ├── COMPUTE_LOG.md | ||||
| 238 | + ├── DECISION_LOG.md | ||||
| 239 | + └── LIMITATIONS.md | ||||
| 240 | +``` | ||||
| 241 | + | ||||
| 242 | +Use relative paths. No user-specific absolute path may appear in committed code. | ||||
| 243 | + | ||||
| 244 | +--- | ||||
| 245 | + | ||||
| 246 | +# 3. Execution protocol | ||||
| 247 | + | ||||
| 248 | +## 3.1 Work in stages | ||||
| 249 | + | ||||
| 250 | +Execute the project in the following order: | ||||
| 251 | + | ||||
| 252 | +### Stage A — Dataset discovery and minimal probe | ||||
| 253 | +Do not download the entire dataset immediately. First: | ||||
| 254 | + | ||||
| 255 | +1. inspect the Hugging Face repository metadata; | ||||
| 256 | +2. list all files, sizes, hashes if available, and last-modified information; | ||||
| 257 | +3. inspect the dataset card and revision history; | ||||
| 258 | +4. download only one early, one middle, and one recent monthly file; | ||||
| 259 | +5. infer the physical schema; | ||||
| 260 | +6. inspect timestamps, symbols, row counts, missingness, duplicates, price and volume units; | ||||
| 261 | +7. estimate total storage requirements after download, decompression, cleaning, features, and outputs; | ||||
| 262 | +8. write `docs/DATA_AUDIT.md` with preliminary findings; | ||||
| 263 | +9. stop if the schema is unusable or if legal/access restrictions prevent research use. | ||||
| 264 | + | ||||
| 265 | +### Stage B — Full download with manifest and resumability | ||||
| 266 | +Only after Stage A passes: | ||||
| 267 | + | ||||
| 268 | +1. download all target files; | ||||
| 269 | +2. use resumable transfers; | ||||
| 270 | +3. pin the exact dataset revision or commit hash; | ||||
| 271 | +4. save every file with checksum, byte size, row count, schema, and download timestamp; | ||||
| 272 | +5. never silently overwrite an existing file; | ||||
| 273 | +6. verify integrity before marking a file complete; | ||||
| 274 | +7. write a machine-readable manifest; | ||||
| 275 | +8. permit partial reruns and node-level parallelism. | ||||
| 276 | + | ||||
| 277 | +### Stage C — Raw-data audit | ||||
| 278 | +Before constructing returns: | ||||
| 279 | + | ||||
| 280 | +1. audit timestamp coverage; | ||||
| 281 | +2. map timestamps to the correct exchange timezone; | ||||
| 282 | +3. identify pre-market, regular, and after-hours observations; | ||||
| 283 | +4. inspect daylight-saving transitions; | ||||
| 284 | +5. compare observed minutes with the official U.S. exchange calendar; | ||||
| 285 | +6. identify half-days and exceptional closures; | ||||
| 286 | +7. detect duplicate symbol–timestamp observations; | ||||
| 287 | +8. detect non-monotonic timestamps; | ||||
| 288 | +9. detect impossible OHLC relationships; | ||||
| 289 | +10. inspect zeros, negative values, stale prices, and extreme volume; | ||||
| 290 | +11. identify possible split-related jumps; | ||||
| 291 | +12. inspect symbol reuse and ticker changes; | ||||
| 292 | +13. determine whether delisted securities are present; | ||||
| 293 | +14. quantify survivorship and look-ahead risks; | ||||
| 294 | +15. identify ETFs, ADRs, preferred shares, warrants, funds, and non-common-equity instruments where possible; | ||||
| 295 | +16. document uncertainty rather than guessing. | ||||
| 296 | + | ||||
| 297 | +### Stage D — Clean panel and metadata | ||||
| 298 | +Construct: | ||||
| 299 | + | ||||
| 300 | +- a regular-hours baseline panel; | ||||
| 301 | +- an extended-hours robustness panel; | ||||
| 302 | +- a broad universe; | ||||
| 303 | +- a conservative common-stock universe; | ||||
| 304 | +- a high-liquidity universe; | ||||
| 305 | +- a balanced-panel subsample only for diagnostics, never as the sole main sample. | ||||
| 306 | + | ||||
| 307 | +### Stage E — Descriptive evidence | ||||
| 308 | +Document: | ||||
| 309 | + | ||||
| 310 | +- sample coverage over time; | ||||
| 311 | +- number of securities; | ||||
| 312 | +- number of observations; | ||||
| 313 | +- missing minute patterns; | ||||
| 314 | +- intraday seasonality; | ||||
| 315 | +- cross-sectional distributions; | ||||
| 316 | +- volume concentration; | ||||
| 317 | +- volatility concentration; | ||||
| 318 | +- extreme-return frequency; | ||||
| 319 | +- changes over decades. | ||||
| 320 | + | ||||
| 321 | +### Stage F — Shock measurement and propagation | ||||
| 322 | +Implement the full empirical design described below. | ||||
| 323 | + | ||||
| 324 | +### Stage G — Tables, figures, and paper | ||||
| 325 | +All tables and figures must be generated from saved results. Never manually type numerical results into LaTeX. | ||||
| 326 | + | ||||
| 327 | +--- | ||||
| 328 | + | ||||
| 329 | +# 4. Data acquisition requirements | ||||
| 330 | + | ||||
| 331 | +## 4.1 Hugging Face access | ||||
| 332 | + | ||||
| 333 | +Use official Hugging Face tooling when practical: | ||||
| 334 | + | ||||
| 335 | +- `huggingface_hub` | ||||
| 336 | +- `hf_hub_download` | ||||
| 337 | +- repository file listing APIs | ||||
| 338 | +- revision pinning | ||||
| 339 | +- authenticated access only if required | ||||
| 340 | + | ||||
| 341 | +The downloader must support: | ||||
| 342 | + | ||||
| 343 | +- dry-run mode; | ||||
| 344 | +- file-range filters; | ||||
| 345 | +- year and month filters; | ||||
| 346 | +- retry with exponential backoff; | ||||
| 347 | +- resumability; | ||||
| 348 | +- maximum concurrent downloads; | ||||
| 349 | +- checksum verification; | ||||
| 350 | +- per-file logs; | ||||
| 351 | +- node-aware sharding; | ||||
| 352 | +- safe interruption; | ||||
| 353 | +- disk-space checks; | ||||
| 354 | +- idempotence. | ||||
| 355 | + | ||||
| 356 | +Create CLI commands such as: | ||||
| 357 | + | ||||
| 358 | +```bash | ||||
| 359 | +python -m intraday_fragility.cli probe-data | ||||
| 360 | +python -m intraday_fragility.cli download --start 1992-01 --end 2026-12 | ||||
| 361 | +python -m intraday_fragility.cli verify-download | ||||
| 362 | +python -m intraday_fragility.cli audit-raw | ||||
| 363 | +``` | ||||
| 364 | + | ||||
| 365 | +## 4.2 Manifest | ||||
| 366 | + | ||||
| 367 | +Create `data/manifests/raw_files.parquet` and `data/manifests/raw_files.csv` with at least: | ||||
| 368 | + | ||||
| 369 | +- dataset_id; | ||||
| 370 | +- dataset_revision; | ||||
| 371 | +- remote_path; | ||||
| 372 | +- local_path; | ||||
| 373 | +- year; | ||||
| 374 | +- month; | ||||
| 375 | +- expected_bytes; | ||||
| 376 | +- downloaded_bytes; | ||||
| 377 | +- sha256; | ||||
| 378 | +- status; | ||||
| 379 | +- download_started_at; | ||||
| 380 | +- download_completed_at; | ||||
| 381 | +- row_count; | ||||
| 382 | +- column_names; | ||||
| 383 | +- column_types; | ||||
| 384 | +- min_timestamp; | ||||
| 385 | +- max_timestamp; | ||||
| 386 | +- unique_symbol_count; | ||||
| 387 | +- duplicate_key_count; | ||||
| 388 | +- null_count_by_column; | ||||
| 389 | +- audit_version; | ||||
| 390 | +- code_commit. | ||||
| 391 | + | ||||
| 392 | +## 4.3 Never infer undocumented semantics | ||||
| 393 | + | ||||
| 394 | +For each field, determine and document: | ||||
| 395 | + | ||||
| 396 | +- exact name; | ||||
| 397 | +- data type; | ||||
| 398 | +- units; | ||||
| 399 | +- timezone; | ||||
| 400 | +- adjustment status; | ||||
| 401 | +- whether price is raw or split-adjusted; | ||||
| 402 | +- whether volume is raw or adjusted; | ||||
| 403 | +- whether timestamps denote bar open or bar close; | ||||
| 404 | +- whether bars with no trades are omitted or filled; | ||||
| 405 | +- whether symbols are point-in-time; | ||||
| 406 | +- whether source corrections are incorporated. | ||||
| 407 | + | ||||
| 408 | +If a property cannot be established, label it “unknown” and design robustness checks around that uncertainty. | ||||
| 409 | + | ||||
| 410 | +--- | ||||
| 411 | + | ||||
| 412 | +# 5. Data-quality audit | ||||
| 413 | + | ||||
| 414 | +## 5.1 Schema validation | ||||
| 415 | + | ||||
| 416 | +For every file and every batch, verify: | ||||
| 417 | + | ||||
| 418 | +\[ | ||||
| 419 | +\text{Low}_{i,t} \leq \min(\text{Open}_{i,t},\text{Close}_{i,t}) | ||||
| 420 | +\] | ||||
| 421 | + | ||||
| 422 | +and | ||||
| 423 | + | ||||
| 424 | +\[ | ||||
| 425 | +\text{High}_{i,t} \geq \max(\text{Open}_{i,t},\text{Close}_{i,t}) | ||||
| 426 | +\] | ||||
| 427 | + | ||||
| 428 | +as well as: | ||||
| 429 | + | ||||
| 430 | +\[ | ||||
| 431 | +\text{Low}_{i,t} \leq \text{High}_{i,t}. | ||||
| 432 | +\] | ||||
| 433 | + | ||||
| 434 | +Flag but do not automatically delete all violations. Report counts, rates, symbols, dates, and magnitudes. | ||||
| 435 | + | ||||
| 436 | +## 5.2 Timestamp and calendar checks | ||||
| 437 | + | ||||
| 438 | +Use a recognized exchange-calendar library and independently validate important dates. | ||||
| 439 | + | ||||
| 440 | +Baseline regular session: | ||||
| 441 | + | ||||
| 442 | +- 09:30 to 16:00 Eastern Time; | ||||
| 443 | +- respect historical calendar variation; | ||||
| 444 | +- handle early closes; | ||||
| 445 | +- handle daylight saving correctly; | ||||
| 446 | +- do not assume exactly 390 bars for every date. | ||||
| 447 | + | ||||
| 448 | +Determine whether the source timestamps are UTC, local exchange time, or another convention by empirical checks. | ||||
| 449 | + | ||||
| 450 | +## 5.3 Duplicate handling | ||||
| 451 | + | ||||
| 452 | +The natural key is initially assumed to be: | ||||
| 453 | + | ||||
| 454 | +```text | ||||
| 455 | +(symbol, timestamp) | ||||
| 456 | +``` | ||||
| 457 | + | ||||
| 458 | +But this assumption must be verified. | ||||
| 459 | + | ||||
| 460 | +For duplicate keys: | ||||
| 461 | + | ||||
| 462 | +1. check whether rows are identical; | ||||
| 463 | +2. inspect whether duplicates arise from multiple venues or source revisions; | ||||
| 464 | +3. preserve raw copies; | ||||
| 465 | +4. create deterministic resolution rules; | ||||
| 466 | +5. report sensitivity to alternative rules. | ||||
| 467 | + | ||||
| 468 | +## 5.4 Corporate actions | ||||
| 469 | + | ||||
| 470 | +OHLCV-based research is highly vulnerable to splits and ticker changes. | ||||
| 471 | + | ||||
| 472 | +Implement: | ||||
| 473 | + | ||||
| 474 | +- detection of discontinuities near rational split ratios; | ||||
| 475 | +- cross-checking against external corporate-action sources if legally and technically feasible; | ||||
| 476 | +- split flags; | ||||
| 477 | +- exclusion windows around suspected splits; | ||||
| 478 | +- robustness using close-to-close versus open-to-close returns; | ||||
| 479 | +- separate treatment of extreme jumps plausibly caused by corporate actions. | ||||
| 480 | + | ||||
| 481 | +Never winsorize away a possible split without logging it. | ||||
| 482 | + | ||||
| 483 | +## 5.5 Security identity | ||||
| 484 | + | ||||
| 485 | +A ticker is not a permanent security identifier. | ||||
| 486 | + | ||||
| 487 | +Attempt to construct or merge a point-in-time security master containing: | ||||
| 488 | + | ||||
| 489 | +- ticker; | ||||
| 490 | +- permanent identifier if available; | ||||
| 491 | +- issuer name; | ||||
| 492 | +- security type; | ||||
| 493 | +- exchange; | ||||
| 494 | +- listing and delisting dates; | ||||
| 495 | +- sector and industry; | ||||
| 496 | +- ETF indicator; | ||||
| 497 | +- ADR indicator; | ||||
| 498 | +- common-stock indicator; | ||||
| 499 | +- share class. | ||||
| 500 | + | ||||
| 501 | +If permanent identifiers cannot be recovered for the full period: | ||||
| 502 | + | ||||
| 503 | +- explicitly state this limitation; | ||||
| 504 | +- avoid interpreting long ticker histories as one unchanged security; | ||||
| 505 | +- create ticker-spell intervals; | ||||
| 506 | +- run conservative analyses within continuous ticker episodes. | ||||
| 507 | + | ||||
| 508 | +## 5.6 Survivorship bias | ||||
| 509 | + | ||||
| 510 | +Determine whether the data include delisted securities and whether historical files preserve the contemporaneous universe. | ||||
| 511 | + | ||||
| 512 | +Produce: | ||||
| 513 | + | ||||
| 514 | +- yearly entry counts; | ||||
| 515 | +- yearly exit counts; | ||||
| 516 | +- symbol survival curves; | ||||
| 517 | +- sample counts by vintage; | ||||
| 518 | +- comparisons of balanced and unbalanced panels; | ||||
| 519 | +- a formal discussion of possible survivorship bias. | ||||
| 520 | + | ||||
| 521 | +## 5.7 Missingness | ||||
| 522 | + | ||||
| 523 | +Measure missingness at: | ||||
| 524 | + | ||||
| 525 | +- file level; | ||||
| 526 | +- day level; | ||||
| 527 | +- symbol-day level; | ||||
| 528 | +- minute-of-day level; | ||||
| 529 | +- decade level; | ||||
| 530 | +- market-state level. | ||||
| 531 | + | ||||
| 532 | +Do not forward-fill prices in the main analysis unless the precise estimand requires a regular grid. If a regular grid is needed: | ||||
| 533 | + | ||||
| 534 | +- distinguish “no recorded bar” from “zero return”; | ||||
| 535 | +- retain a missing-trade indicator; | ||||
| 536 | +- report results without imputation; | ||||
| 537 | +- use previous-tick interpolation only in explicitly labeled robustness analyses. | ||||
| 538 | + | ||||
| 539 | +--- | ||||
| 540 | + | ||||
| 541 | +# 6. Sample construction | ||||
| 542 | + | ||||
| 543 | +Create transparent sample filters in `config/sample_filters.yaml`. | ||||
| 544 | + | ||||
| 545 | +## 6.1 Baseline universe | ||||
| 546 | + | ||||
| 547 | +The baseline should target U.S.-listed common equities during regular trading hours, subject to defensible filters such as: | ||||
| 548 | + | ||||
| 549 | +- valid OHLC; | ||||
| 550 | +- positive price; | ||||
| 551 | +- positive or nonnegative volume as appropriate; | ||||
| 552 | +- minimum number of valid bars per day; | ||||
| 553 | +- minimum trading history; | ||||
| 554 | +- exclusion of obvious corporate-action contamination; | ||||
| 555 | +- removal of duplicate records; | ||||
| 556 | +- no use of future information in inclusion rules. | ||||
| 557 | + | ||||
| 558 | +## 6.2 Alternative universes | ||||
| 559 | + | ||||
| 560 | +Construct at least: | ||||
| 561 | + | ||||
| 562 | +1. all available instruments; | ||||
| 563 | +2. common stocks only; | ||||
| 564 | +3. stocks excluding ETFs and ADRs; | ||||
| 565 | +4. liquid stocks based on lagged information; | ||||
| 566 | +5. price above a lagged threshold; | ||||
| 567 | +6. top 500, 1,000, and 3,000 securities by lagged dollar volume; | ||||
| 568 | +7. continuous-history subsample; | ||||
| 569 | +8. pre-2001, 2001–2009, 2010–2019, and 2020 onward; | ||||
| 570 | +9. regular-hours only; | ||||
| 571 | +10. extended-hours included. | ||||
| 572 | + | ||||
| 573 | +Any liquidity-based inclusion criterion must use lagged data to avoid look-ahead bias. | ||||
| 574 | + | ||||
| 575 | +--- | ||||
| 576 | + | ||||
| 577 | +# 7. Variable construction | ||||
| 578 | + | ||||
| 579 | +All features must be defined in `docs/DATA_DICTIONARY.md` with formula, timing, units, and availability. | ||||
| 580 | + | ||||
| 581 | +## 7.1 Returns | ||||
| 582 | + | ||||
| 583 | +Construct: | ||||
| 584 | + | ||||
| 585 | +\[ | ||||
| 586 | +r_{i,t} = \log(P_{i,t})-\log(P_{i,t-1}). | ||||
| 587 | +\] | ||||
| 588 | + | ||||
| 589 | +Use alternative prices: | ||||
| 590 | + | ||||
| 591 | +- close-to-close minute return; | ||||
| 592 | +- open-to-close bar return; | ||||
| 593 | +- midpoint proxy \((H+L)/2\) only as robustness; | ||||
| 594 | +- previous valid close return; | ||||
| 595 | +- overnight return separately. | ||||
| 596 | + | ||||
| 597 | +Never bridge overnight and intraday returns without an explicit definition. | ||||
| 598 | + | ||||
| 599 | +## 7.2 Realized volatility | ||||
| 600 | + | ||||
| 601 | +At stock-day level: | ||||
| 602 | + | ||||
| 603 | +\[ | ||||
| 604 | +RV_{i,d} = \sum_{t \in d} r_{i,t}^{2}. | ||||
| 605 | +\] | ||||
| 606 | + | ||||
| 607 | +Construct: | ||||
| 608 | + | ||||
| 609 | +- 5-minute RV; | ||||
| 610 | +- 15-minute RV; | ||||
| 611 | +- 30-minute RV; | ||||
| 612 | +- daily RV; | ||||
| 613 | +- upside and downside semivariance; | ||||
| 614 | +- bipower variation if data quality permits; | ||||
| 615 | +- jump proxies; | ||||
| 616 | +- realized quarticity. | ||||
| 617 | + | ||||
| 618 | +## 7.3 Range-based measures | ||||
| 619 | + | ||||
| 620 | +Examples: | ||||
| 621 | + | ||||
| 622 | +\[ | ||||
| 623 | +Range_{i,t}=\log(H_{i,t})-\log(L_{i,t}) | ||||
| 624 | +\] | ||||
| 625 | + | ||||
| 626 | +and established range-based volatility estimators when their assumptions are defensible. | ||||
| 627 | + | ||||
| 628 | +## 7.4 Trading activity | ||||
| 629 | + | ||||
| 630 | +Construct: | ||||
| 631 | + | ||||
| 632 | +- raw volume; | ||||
| 633 | +- log volume; | ||||
| 634 | +- dollar volume; | ||||
| 635 | +- turnover if shares outstanding become available; | ||||
| 636 | +- volume relative to the same minute of the day; | ||||
| 637 | +- volume z-score based only on lagged observations; | ||||
| 638 | +- fraction of daily volume occurring in each interval; | ||||
| 639 | +- market-wide and sector-wide volume concentration. | ||||
| 640 | + | ||||
| 641 | +## 7.5 OHLCV-based illiquidity and price-impact proxies | ||||
| 642 | + | ||||
| 643 | +Possible proxies include: | ||||
| 644 | + | ||||
| 645 | +\[ | ||||
| 646 | +ILLIQ_{i,t} = \frac{|r_{i,t}|}{DollarVolume_{i,t}+\epsilon}. | ||||
| 647 | +\] | ||||
| 648 | + | ||||
| 649 | +Also consider: | ||||
| 650 | + | ||||
| 651 | +- high-low range divided by dollar volume; | ||||
| 652 | +- absolute residual return per unit of volume; | ||||
| 653 | +- zero-return frequency; | ||||
| 654 | +- stale-price duration; | ||||
| 655 | +- Roll-type proxies only if valid at the available frequency; | ||||
| 656 | +- Corwin–Schultz estimates only at a frequency consistent with the estimator. | ||||
| 657 | + | ||||
| 658 | +Use multiple proxies because no single OHLCV measure identifies true liquidity. | ||||
| 659 | + | ||||
| 660 | +## 7.6 Intraday seasonality | ||||
| 661 | + | ||||
| 662 | +For each variable, estimate minute-of-day seasonality using only historical information or a clearly defined full-sample descriptive normalization. | ||||
| 663 | + | ||||
| 664 | +Main predictive and causal specifications must use lagged or training-period seasonality estimates. | ||||
| 665 | + | ||||
| 666 | +Construct standardized variables: | ||||
| 667 | + | ||||
| 668 | +\[ | ||||
| 669 | +z_{i,t}^{x} | ||||
| 670 | += | ||||
| 671 | +\frac{x_{i,t}-\widehat{\mu}_{i,\tau(t)}}{\widehat{\sigma}_{i,\tau(t)}}, | ||||
| 672 | +\] | ||||
| 673 | + | ||||
| 674 | +where \(\tau(t)\) is minute of day. | ||||
| 675 | + | ||||
| 676 | +Use robust alternatives based on the median and MAD. | ||||
| 677 | + | ||||
| 678 | +--- | ||||
| 679 | + | ||||
| 680 | +# 8. Defining idiosyncratic intraday shocks | ||||
| 681 | + | ||||
| 682 | +A raw extreme return is not necessarily idiosyncratic. Construct several shock definitions. | ||||
| 683 | + | ||||
| 684 | +## 8.1 Residual return model | ||||
| 685 | + | ||||
| 686 | +Estimate rolling or recursively updated models such as: | ||||
| 687 | + | ||||
| 688 | +\[ | ||||
| 689 | +r_{i,t} | ||||
| 690 | += | ||||
| 691 | +\alpha_{i,\tau} | ||||
| 692 | ++\beta_{i,m,t}r_{m,t} | ||||
| 693 | ++\beta_{i,s,t}r_{s(i),t} | ||||
| 694 | ++\boldsymbol{\gamma}_{i,t}'F_t | ||||
| 695 | ++\varepsilon_{i,t}, | ||||
| 696 | +\] | ||||
| 697 | + | ||||
| 698 | +where: | ||||
| 699 | + | ||||
| 700 | +- \(r_{m,t}\) is a broad market return; | ||||
| 701 | +- \(r_{s(i),t}\) is the sector return; | ||||
| 702 | +- \(F_t\) may contain principal components or other common factors; | ||||
| 703 | +- \(\alpha_{i,\tau}\) absorbs intraday seasonality. | ||||
| 704 | + | ||||
| 705 | +Prevent mechanical contamination by excluding stock \(i\) from market and sector aggregates when feasible. | ||||
| 706 | + | ||||
| 707 | +## 8.2 Shock threshold | ||||
| 708 | + | ||||
| 709 | +Define a baseline shock as: | ||||
| 710 | + | ||||
| 711 | +\[ | ||||
| 712 | +Shock_{i,t}=1\left( | ||||
| 713 | +|\varepsilon_{i,t}| > | ||||
| 714 | +q_{i,\tau,t}(p) | ||||
| 715 | +\right), | ||||
| 716 | +\] | ||||
| 717 | + | ||||
| 718 | +where \(q_{i,\tau,t}(p)\) is a lagged conditional extreme quantile. | ||||
| 719 | + | ||||
| 720 | +Use thresholds such as: | ||||
| 721 | + | ||||
| 722 | +- 99th percentile; | ||||
| 723 | +- 99.5th percentile; | ||||
| 724 | +- 99.9th percentile; | ||||
| 725 | +- 4, 5, and 6 robust standard deviations; | ||||
| 726 | +- extreme-value-theory thresholds; | ||||
| 727 | +- jump-test thresholds. | ||||
| 728 | + | ||||
| 729 | +Separate: | ||||
| 730 | + | ||||
| 731 | +- positive shocks; | ||||
| 732 | +- negative shocks; | ||||
| 733 | +- return shocks; | ||||
| 734 | +- volatility shocks; | ||||
| 735 | +- volume shocks; | ||||
| 736 | +- combined return-volume shocks; | ||||
| 737 | +- range shocks; | ||||
| 738 | +- illiquidity-proxy shocks. | ||||
| 739 | + | ||||
| 740 | +## 8.3 Shock isolation | ||||
| 741 | + | ||||
| 742 | +To reduce common-news contamination, require one or more of: | ||||
| 743 | + | ||||
| 744 | +- low contemporaneous market return; | ||||
| 745 | +- low contemporaneous sector return; | ||||
| 746 | +- large idiosyncratic residual; | ||||
| 747 | +- leave-one-out factor construction; | ||||
| 748 | +- no simultaneous extreme shock in a large fraction of the market; | ||||
| 749 | +- exclusion of scheduled macro announcement windows for the idiosyncratic baseline; | ||||
| 750 | +- separate common-shock sample. | ||||
| 751 | + | ||||
| 752 | +Do not define isolation so strictly that only trivial events remain. Report the trade-off. | ||||
| 753 | + | ||||
| 754 | +--- | ||||
| 755 | + | ||||
| 756 | +# 9. Measuring propagation | ||||
| 757 | + | ||||
| 758 | +## 9.1 Outcome horizons | ||||
| 759 | + | ||||
| 760 | +Use horizons: | ||||
| 761 | + | ||||
| 762 | +\[ | ||||
| 763 | +h \in \{1,2,5,10,15,30,60,120\}\text{ minutes}. | ||||
| 764 | +\] | ||||
| 765 | + | ||||
| 766 | +Respect session boundaries. Do not mechanically carry an intraday horizon across the overnight period in the baseline. | ||||
| 767 | + | ||||
| 768 | +## 9.2 Breadth | ||||
| 769 | + | ||||
| 770 | +Define market-wide propagation breadth: | ||||
| 771 | + | ||||
| 772 | +\[ | ||||
| 773 | +Breadth_{i,t}(h) | ||||
| 774 | += | ||||
| 775 | +\frac{1}{N_{t,h}-1} | ||||
| 776 | +\sum_{j\neq i} | ||||
| 777 | +1\left(|AR_{j,t+h}|>q_{j,\tau,t}\right). | ||||
| 778 | +\] | ||||
| 779 | + | ||||
| 780 | +Also define: | ||||
| 781 | + | ||||
| 782 | +- cumulative breadth through \(h\); | ||||
| 783 | +- sector breadth; | ||||
| 784 | +- connected-neighbor breadth; | ||||
| 785 | +- non-sector breadth; | ||||
| 786 | +- breadth weighted by lagged dollar volume; | ||||
| 787 | +- breadth weighted by network proximity. | ||||
| 788 | + | ||||
| 789 | +## 9.3 Speed | ||||
| 790 | + | ||||
| 791 | +Define: | ||||
| 792 | + | ||||
| 793 | +- minutes until 1%, 5%, 10%, or 25% of eligible securities react; | ||||
| 794 | +- time to peak breadth; | ||||
| 795 | +- half-life of the response; | ||||
| 796 | +- propagation velocity over network distance; | ||||
| 797 | +- hazard of first response. | ||||
| 798 | + | ||||
| 799 | +If a threshold is never reached, treat the observation as right-censored rather than assigning an arbitrary large value. | ||||
| 800 | + | ||||
| 801 | +## 9.4 Intensity | ||||
| 802 | + | ||||
| 803 | +Define: | ||||
| 804 | + | ||||
| 805 | +\[ | ||||
| 806 | +Intensity_{i,t}(h) | ||||
| 807 | += | ||||
| 808 | +\frac{1}{N-1} | ||||
| 809 | +\sum_{j\neq i}|AR_{j,t+h}|. | ||||
| 810 | +\] | ||||
| 811 | + | ||||
| 812 | +Construct signed and unsigned versions. | ||||
| 813 | + | ||||
| 814 | +## 9.5 Amplification | ||||
| 815 | + | ||||
| 816 | +Define the Intraday Shock Amplification Ratio: | ||||
| 817 | + | ||||
| 818 | +\[ | ||||
| 819 | +ISAR_{i,t}(h) | ||||
| 820 | += | ||||
| 821 | +\frac{ | ||||
| 822 | +\sum_{j\neq i}w_{ij,t}|AR_{j,t+h}| | ||||
| 823 | +}{ | ||||
| 824 | +|\varepsilon_{i,t}|+\epsilon | ||||
| 825 | +}. | ||||
| 826 | +\] | ||||
| 827 | + | ||||
| 828 | +Explore alternative normalizations and show that results are not artifacts of a small denominator. | ||||
| 829 | + | ||||
| 830 | +## 9.6 Persistence | ||||
| 831 | + | ||||
| 832 | +Measure: | ||||
| 833 | + | ||||
| 834 | +- cumulative response; | ||||
| 835 | +- response half-life; | ||||
| 836 | +- reversal after the initial response; | ||||
| 837 | +- permanent versus transitory components; | ||||
| 838 | +- integrated response over 5, 15, 30, 60, and 120 minutes. | ||||
| 839 | + | ||||
| 840 | +## 9.7 Asymmetry | ||||
| 841 | + | ||||
| 842 | +Estimate separate responses to: | ||||
| 843 | + | ||||
| 844 | +- positive versus negative shocks; | ||||
| 845 | +- high versus low market volatility; | ||||
| 846 | +- opening, midday, and closing periods; | ||||
| 847 | +- high versus low aggregate correlation; | ||||
| 848 | +- high versus low market concentration; | ||||
| 849 | +- liquid versus illiquid source securities; | ||||
| 850 | +- large versus small shock magnitude. | ||||
| 851 | + | ||||
| 852 | +--- | ||||
| 853 | + | ||||
| 854 | +# 10. Dynamic network construction | ||||
| 855 | + | ||||
| 856 | +The network must be estimated using information available before the shock. | ||||
| 857 | + | ||||
| 858 | +## 10.1 Candidate networks | ||||
| 859 | + | ||||
| 860 | +Estimate several networks: | ||||
| 861 | + | ||||
| 862 | +1. sector membership; | ||||
| 863 | +2. rolling return correlation; | ||||
| 864 | +3. partial correlation; | ||||
| 865 | +4. lead-lag predictive network; | ||||
| 866 | +5. volume-shock correlation; | ||||
| 867 | +6. volatility-spillover network; | ||||
| 868 | +7. sparse VAR; | ||||
| 869 | +8. graphical LASSO; | ||||
| 870 | +9. low-rank plus sparse network; | ||||
| 871 | +10. dynamic factor residual network; | ||||
| 872 | +11. Granger-style predictive network; | ||||
| 873 | +12. learned graph representation, used as an extension rather than the sole method. | ||||
| 874 | + | ||||
| 875 | +## 10.2 Timing discipline | ||||
| 876 | + | ||||
| 877 | +For a shock at time \(t\), network weights \(W_{ij,t}\) must be estimated only from data dated strictly before \(t\). | ||||
| 878 | + | ||||
| 879 | +Use: | ||||
| 880 | + | ||||
| 881 | +- rolling windows; | ||||
| 882 | +- expanding windows; | ||||
| 883 | +- annual network freezes; | ||||
| 884 | +- monthly network freezes; | ||||
| 885 | +- cross-fitted network estimation. | ||||
| 886 | + | ||||
| 887 | +## 10.3 Centrality and roles | ||||
| 888 | + | ||||
| 889 | +Compute lagged: | ||||
| 890 | + | ||||
| 891 | +- out-strength; | ||||
| 892 | +- in-strength; | ||||
| 893 | +- eigenvector centrality; | ||||
| 894 | +- PageRank; | ||||
| 895 | +- betweenness; | ||||
| 896 | +- community bridge score; | ||||
| 897 | +- k-core; | ||||
| 898 | +- participation coefficient; | ||||
| 899 | +- transmitter and receiver scores. | ||||
| 900 | + | ||||
| 901 | +Define economic roles: | ||||
| 902 | + | ||||
| 903 | +- transmitter; | ||||
| 904 | +- receiver; | ||||
| 905 | +- amplifier; | ||||
| 906 | +- absorber; | ||||
| 907 | +- bridge; | ||||
| 908 | +- isolated security. | ||||
| 909 | + | ||||
| 910 | +Do not infer economic importance from one centrality measure alone. | ||||
| 911 | + | ||||
| 912 | +--- | ||||
| 913 | + | ||||
| 914 | +# 11. Baseline econometric designs | ||||
| 915 | + | ||||
| 916 | +## 11.1 Local projections | ||||
| 917 | + | ||||
| 918 | +Estimate horizon-specific responses: | ||||
| 919 | + | ||||
| 920 | +\[ | ||||
| 921 | +Y_{j,t+h} | ||||
| 922 | += | ||||
| 923 | +\alpha_{j} | ||||
| 924 | ++\delta_{\tau(t)} | ||||
| 925 | ++\lambda_{d} | ||||
| 926 | ++\beta_h Shock_{i,t} | ||||
| 927 | ++\theta_h Shock_{i,t}W_{ij,t^-} | ||||
| 928 | ++\Gamma_h'X_{i,j,t^-} | ||||
| 929 | ++u_{i,j,t+h}. | ||||
| 930 | +\] | ||||
| 931 | + | ||||
| 932 | +Possible fixed effects: | ||||
| 933 | + | ||||
| 934 | +- receiver security; | ||||
| 935 | +- source security; | ||||
| 936 | +- date; | ||||
| 937 | +- minute of day; | ||||
| 938 | +- source-by-year; | ||||
| 939 | +- receiver-by-year; | ||||
| 940 | +- sector-by-date; | ||||
| 941 | +- market-state bins. | ||||
| 942 | + | ||||
| 943 | +Do not include fixed effects that absorb the variable of interest without recognizing it. | ||||
| 944 | + | ||||
| 945 | +## 11.2 Cascade-level regressions | ||||
| 946 | + | ||||
| 947 | +At the source-shock level: | ||||
| 948 | + | ||||
| 949 | +\[ | ||||
| 950 | +Cascade_{i,t}(h) | ||||
| 951 | += | ||||
| 952 | +\alpha | ||||
| 953 | ++\beta_1 Magnitude_{i,t} | ||||
| 954 | ++\beta_2 Negative_{i,t} | ||||
| 955 | ++\beta_3 Centrality_{i,t^-} | ||||
| 956 | ++\beta_4 State_{t^-} | ||||
| 957 | ++\beta_5 Magnitude_{i,t}\times State_{t^-} | ||||
| 958 | ++\mu_i+\lambda_d+\delta_{\tau} | ||||
| 959 | ++\varepsilon_{i,t,h}. | ||||
| 960 | +\] | ||||
| 961 | + | ||||
| 962 | +## 11.3 Long-run evolution | ||||
| 963 | + | ||||
| 964 | +Estimate flexible time variation: | ||||
| 965 | + | ||||
| 966 | +- year fixed effects interacted with shock magnitude; | ||||
| 967 | +- rolling coefficients; | ||||
| 968 | +- decade bins; | ||||
| 969 | +- splines; | ||||
| 970 | +- structural-break tests; | ||||
| 971 | +- distributional regressions; | ||||
| 972 | +- quantile regressions. | ||||
| 973 | + | ||||
| 974 | +Do not impose a linear “algorithmic trading trend” as the only model. | ||||
| 975 | + | ||||
| 976 | +## 11.4 Nonlinearity | ||||
| 977 | + | ||||
| 978 | +Test whether propagation changes sharply beyond a threshold: | ||||
| 979 | + | ||||
| 980 | +- binscatter with confidence intervals; | ||||
| 981 | +- local polynomial; | ||||
| 982 | +- splines; | ||||
| 983 | +- threshold regression; | ||||
| 984 | +- generalized random forest for heterogeneity; | ||||
| 985 | +- quantile treatment effects where appropriate; | ||||
| 986 | +- monotonicity checks. | ||||
| 987 | + | ||||
| 988 | +The primary nonlinear result must also be represented with a transparent non-ML specification. | ||||
| 989 | + | ||||
| 990 | +## 11.5 Inference | ||||
| 991 | + | ||||
| 992 | +High-frequency observations are strongly dependent. | ||||
| 993 | + | ||||
| 994 | +Consider: | ||||
| 995 | + | ||||
| 996 | +- two-way clustering by source security and date; | ||||
| 997 | +- clustering by date and minute block; | ||||
| 998 | +- source-shock-level aggregation; | ||||
| 999 | +- block bootstrap by trading day; | ||||
| 1000 | +- stationary bootstrap; | ||||
| 1001 | +- randomization inference for event studies; | ||||
| 1002 | +- Driscoll–Kraay only if its assumptions fit; | ||||
| 1003 | +- multiple-hypothesis correction for families of outcomes. | ||||
| 1004 | + | ||||
| 1005 | +Report why each inference method is appropriate. | ||||
| 1006 | + | ||||
| 1007 | +--- | ||||
| 1008 | + | ||||
| 1009 | +# 12. Identification and common-information problem | ||||
| 1010 | + | ||||
| 1011 | +The central threat is that many securities react to the same information rather than to each other. | ||||
| 1012 | + | ||||
| 1013 | +Address this directly. | ||||
| 1014 | + | ||||
| 1015 | +## 12.1 Scheduled macro announcements | ||||
| 1016 | + | ||||
| 1017 | +Construct an event database for major U.S. announcements where reliable historical timestamps and surprise measures are available: | ||||
| 1018 | + | ||||
| 1019 | +- FOMC decisions and statements; | ||||
| 1020 | +- CPI; | ||||
| 1021 | +- employment report; | ||||
| 1022 | +- GDP; | ||||
| 1023 | +- retail sales; | ||||
| 1024 | +- PPI; | ||||
| 1025 | +- ISM; | ||||
| 1026 | +- other major scheduled releases. | ||||
| 1027 | + | ||||
| 1028 | +Use these events to: | ||||
| 1029 | + | ||||
| 1030 | +1. characterize common shocks; | ||||
| 1031 | +2. estimate separate propagation patterns; | ||||
| 1032 | +3. exclude macro windows from the idiosyncratic baseline; | ||||
| 1033 | +4. compare common-news and firm-originating shock dynamics. | ||||
| 1034 | + | ||||
| 1035 | +## 12.2 Firm-specific news | ||||
| 1036 | + | ||||
| 1037 | +If reliable timestamped news or earnings-announcement data can be added: | ||||
| 1038 | + | ||||
| 1039 | +- identify plausibly firm-specific shocks; | ||||
| 1040 | +- distinguish pre-market, intraday, and after-hours announcements; | ||||
| 1041 | +- use narrow event windows; | ||||
| 1042 | +- avoid post-treatment controls; | ||||
| 1043 | +- test whether economically linked firms respond more strongly. | ||||
| 1044 | + | ||||
| 1045 | +Do not use scraped or low-quality event timestamps without validation. | ||||
| 1046 | + | ||||
| 1047 | +## 12.3 Placebo timing | ||||
| 1048 | + | ||||
| 1049 | +For each real shock: | ||||
| 1050 | + | ||||
| 1051 | +- assign same-stock placebo times on comparable non-event days; | ||||
| 1052 | +- preserve minute-of-day and volatility state; | ||||
| 1053 | +- repeat the propagation analysis; | ||||
| 1054 | +- compare real and placebo distributions. | ||||
| 1055 | + | ||||
| 1056 | +## 12.4 Permuted networks | ||||
| 1057 | + | ||||
| 1058 | +Randomly permute network links while preserving: | ||||
| 1059 | + | ||||
| 1060 | +- degree distribution; | ||||
| 1061 | +- sector composition; | ||||
| 1062 | +- size bins; | ||||
| 1063 | +- liquidity bins. | ||||
| 1064 | + | ||||
| 1065 | +True networks should outperform matched placebo networks if network propagation is economically meaningful. | ||||
| 1066 | + | ||||
| 1067 | +## 12.5 Negative controls | ||||
| 1068 | + | ||||
| 1069 | +Potential negative controls: | ||||
| 1070 | + | ||||
| 1071 | +- future network weights; | ||||
| 1072 | +- distant unrelated securities; | ||||
| 1073 | +- pre-shock outcomes; | ||||
| 1074 | +- randomized source identity; | ||||
| 1075 | +- non-overlapping time windows. | ||||
| 1076 | + | ||||
| 1077 | +Future information may be used only as a falsification test, never in the baseline estimator. | ||||
| 1078 | + | ||||
| 1079 | +--- | ||||
| 1080 | + | ||||
| 1081 | +# 13. Market-structure evolution | ||||
| 1082 | + | ||||
| 1083 | +The paper may discuss algorithmic and electronic trading, but OHLCV data do not directly measure algorithmic trading intensity. | ||||
| 1084 | + | ||||
| 1085 | +Therefore: | ||||
| 1086 | + | ||||
| 1087 | +- do not claim a causal effect of algorithmic trading from a time trend alone; | ||||
| 1088 | +- identify documented market-structure milestones from authoritative sources; | ||||
| 1089 | +- treat breakpoint evidence cautiously; | ||||
| 1090 | +- consider alternative explanations: | ||||
| 1091 | + - decimalization; | ||||
| 1092 | + - ETF growth; | ||||
| 1093 | + - passive investment; | ||||
| 1094 | + - market fragmentation; | ||||
| 1095 | + - faster information diffusion; | ||||
| 1096 | + - changes in listing composition; | ||||
| 1097 | + - changes in data coverage; | ||||
| 1098 | + - crisis composition; | ||||
| 1099 | + - regulation; | ||||
| 1100 | + - macro volatility; | ||||
| 1101 | + - changing sector weights. | ||||
| 1102 | + | ||||
| 1103 | +Potential periodization must be pre-specified and justified. Results should also be shown using flexible year effects rather than only hand-picked eras. | ||||
| 1104 | + | ||||
| 1105 | +--- | ||||
| 1106 | + | ||||
| 1107 | +# 14. Machine learning and foundation-model extension | ||||
| 1108 | + | ||||
| 1109 | +A machine-learning component may be included, but it must not obscure identification. | ||||
| 1110 | + | ||||
| 1111 | +## 14.1 Prediction task | ||||
| 1112 | + | ||||
| 1113 | +Predict at shock time \(t\): | ||||
| 1114 | + | ||||
| 1115 | +- future breadth; | ||||
| 1116 | +- future intensity; | ||||
| 1117 | +- time to cascade; | ||||
| 1118 | +- sector-to-market transition; | ||||
| 1119 | +- probability of a tail cascade. | ||||
| 1120 | + | ||||
| 1121 | +## 14.2 Data splitting | ||||
| 1122 | + | ||||
| 1123 | +Use strict temporal splits: | ||||
| 1124 | + | ||||
| 1125 | +- training period; | ||||
| 1126 | +- validation period; | ||||
| 1127 | +- final untouched test period; | ||||
| 1128 | +- optional rolling-origin evaluation. | ||||
| 1129 | + | ||||
| 1130 | +Never randomly split minute observations across train and test. | ||||
| 1131 | + | ||||
| 1132 | +## 14.3 Baselines | ||||
| 1133 | + | ||||
| 1134 | +Compare with: | ||||
| 1135 | + | ||||
| 1136 | +- unconditional historical mean; | ||||
| 1137 | +- linear and logistic regressions; | ||||
| 1138 | +- penalized regression; | ||||
| 1139 | +- random forest; | ||||
| 1140 | +- gradient boosting; | ||||
| 1141 | +- HAR-style models; | ||||
| 1142 | +- VAR and sparse VAR; | ||||
| 1143 | +- Hawkes-inspired specifications where feasible; | ||||
| 1144 | +- LSTM; | ||||
| 1145 | +- temporal convolution; | ||||
| 1146 | +- transformer or state-space model; | ||||
| 1147 | +- graph neural network; | ||||
| 1148 | +- model without network information; | ||||
| 1149 | +- model without market-state information. | ||||
| 1150 | + | ||||
| 1151 | +## 14.4 Evaluation | ||||
| 1152 | + | ||||
| 1153 | +Report: | ||||
| 1154 | + | ||||
| 1155 | +- out-of-sample \(R^2\); | ||||
| 1156 | +- log loss; | ||||
| 1157 | +- Brier score; | ||||
| 1158 | +- AUROC; | ||||
| 1159 | +- precision-recall AUC; | ||||
| 1160 | +- calibration; | ||||
| 1161 | +- tail recall; | ||||
| 1162 | +- economic ranking performance; | ||||
| 1163 | +- stability across years and regimes. | ||||
| 1164 | + | ||||
| 1165 | +No trading strategy should be the main evidence. Any economic-value exercise must incorporate conservative transaction-cost assumptions and be clearly secondary. | ||||
| 1166 | + | ||||
| 1167 | +## 14.5 Interpretability | ||||
| 1168 | + | ||||
| 1169 | +Use: | ||||
| 1170 | + | ||||
| 1171 | +- partial dependence; | ||||
| 1172 | +- accumulated local effects; | ||||
| 1173 | +- SHAP with dependence-aware interpretation; | ||||
| 1174 | +- feature ablation; | ||||
| 1175 | +- network ablation; | ||||
| 1176 | +- temporal ablation; | ||||
| 1177 | +- regime-specific performance; | ||||
| 1178 | +- calibration plots. | ||||
| 1179 | + | ||||
| 1180 | +Do not treat model attention weights as causal explanations. | ||||
| 1181 | + | ||||
| 1182 | +--- | ||||
| 1183 | + | ||||
| 1184 | +# 15. Required robustness analyses | ||||
| 1185 | + | ||||
| 1186 | +At minimum, run: | ||||
| 1187 | + | ||||
| 1188 | +1. alternative return definitions; | ||||
| 1189 | +2. alternative shock thresholds; | ||||
| 1190 | +3. alternative factor residualizations; | ||||
| 1191 | +4. alternative market and sector benchmarks; | ||||
| 1192 | +5. alternative network definitions; | ||||
| 1193 | +6. alternative network estimation windows; | ||||
| 1194 | +7. alternative security universes; | ||||
| 1195 | +8. exclusion of ETFs; | ||||
| 1196 | +9. exclusion of ADRs; | ||||
| 1197 | +10. exclusion of penny stocks; | ||||
| 1198 | +11. exclusion of suspected split windows; | ||||
| 1199 | +12. regular-hours only; | ||||
| 1200 | +13. alternative minute aggregation: 1, 5, 10, and 15 minutes; | ||||
| 1201 | +14. volume-weighted and equal-weighted outcomes; | ||||
| 1202 | +15. opening and closing exclusions; | ||||
| 1203 | +16. crisis versus non-crisis samples; | ||||
| 1204 | +17. macro-announcement exclusions; | ||||
| 1205 | +18. day-block bootstrap; | ||||
| 1206 | +19. matched placebo shocks; | ||||
| 1207 | +20. permuted networks; | ||||
| 1208 | +21. pre-trend and pre-response tests; | ||||
| 1209 | +22. source-stock fixed effects; | ||||
| 1210 | +23. receiver-stock fixed effects; | ||||
| 1211 | +24. date fixed effects; | ||||
| 1212 | +25. sector-by-date fixed effects where computationally feasible; | ||||
| 1213 | +26. balanced versus unbalanced samples; | ||||
| 1214 | +27. winsorized versus non-winsorized outcomes; | ||||
| 1215 | +28. median-based robust standardization; | ||||
| 1216 | +29. alternative right-censoring treatment for propagation time; | ||||
| 1217 | +30. multiple-testing adjustments. | ||||
| 1218 | + | ||||
| 1219 | +Robustness must test the economic interpretation, not merely produce many similar regressions. | ||||
| 1220 | + | ||||
| 1221 | +--- | ||||
| 1222 | + | ||||
| 1223 | +# 16. Falsification tests | ||||
| 1224 | + | ||||
| 1225 | +The project must attempt to disprove its own central claim. | ||||
| 1226 | + | ||||
| 1227 | +Required falsifications include: | ||||
| 1228 | + | ||||
| 1229 | +- no systematic response before the source shock; | ||||
| 1230 | +- weak propagation through randomized networks; | ||||
| 1231 | +- weaker response among economically unrelated stocks; | ||||
| 1232 | +- stronger response after genuine shocks than matched placebo times; | ||||
| 1233 | +- no apparent secular acceleration caused solely by changing sample size; | ||||
| 1234 | +- no apparent acceleration caused solely by timestamp precision or coverage changes; | ||||
| 1235 | +- no result driven by a few crisis days; | ||||
| 1236 | +- no result driven by the largest technology stocks; | ||||
| 1237 | +- no result driven solely by ETFs; | ||||
| 1238 | +- no result generated mechanically by market-factor construction; | ||||
| 1239 | +- no result driven by corporate actions. | ||||
| 1240 | + | ||||
| 1241 | +If a falsification fails, do not hide it. Reassess the claim. | ||||
| 1242 | + | ||||
| 1243 | +--- | ||||
| 1244 | + | ||||
| 1245 | +# 17. Descriptive tables required | ||||
| 1246 | + | ||||
| 1247 | +Generate the following main-paper candidates. | ||||
| 1248 | + | ||||
| 1249 | +## Table I — Sample construction | ||||
| 1250 | + | ||||
| 1251 | +Include by decade or period: | ||||
| 1252 | + | ||||
| 1253 | +- raw rows; | ||||
| 1254 | +- raw symbols; | ||||
| 1255 | +- valid trading days; | ||||
| 1256 | +- duplicate removals; | ||||
| 1257 | +- invalid OHLC removals; | ||||
| 1258 | +- suspected corporate-action exclusions; | ||||
| 1259 | +- final stock-minute observations; | ||||
| 1260 | +- final securities; | ||||
| 1261 | +- median valid minutes per stock-day. | ||||
| 1262 | + | ||||
| 1263 | +## Table II — Summary statistics | ||||
| 1264 | + | ||||
| 1265 | +For core variables: | ||||
| 1266 | + | ||||
| 1267 | +- mean; | ||||
| 1268 | +- standard deviation; | ||||
| 1269 | +- p1; | ||||
| 1270 | +- p5; | ||||
| 1271 | +- median; | ||||
| 1272 | +- p95; | ||||
| 1273 | +- p99; | ||||
| 1274 | +- number of observations. | ||||
| 1275 | + | ||||
| 1276 | +Report at the economically appropriate unit to avoid meaningless precision. | ||||
| 1277 | + | ||||
| 1278 | +## Table III — Characteristics of source shocks | ||||
| 1279 | + | ||||
| 1280 | +Compare: | ||||
| 1281 | + | ||||
| 1282 | +- positive and negative shocks; | ||||
| 1283 | +- low- and high-volatility states; | ||||
| 1284 | +- early and late sample; | ||||
| 1285 | +- cascade and non-cascade shocks. | ||||
| 1286 | + | ||||
| 1287 | +## Table IV — Baseline propagation | ||||
| 1288 | + | ||||
| 1289 | +Show horizon-specific coefficients for breadth, intensity, and persistence. | ||||
| 1290 | + | ||||
| 1291 | +## Table V — Nonlinearity and asymmetry | ||||
| 1292 | + | ||||
| 1293 | +Show shock-size bins, negative interaction, and market-state interactions. | ||||
| 1294 | + | ||||
| 1295 | +## Table VI — Evolution over time | ||||
| 1296 | + | ||||
| 1297 | +Show flexible period or year interactions and tests of equality. | ||||
| 1298 | + | ||||
| 1299 | +## Table VII — Network mechanisms | ||||
| 1300 | + | ||||
| 1301 | +Compare connected and unconnected receivers and transmitter centrality. | ||||
| 1302 | + | ||||
| 1303 | +## Table VIII — Identification and placebo tests | ||||
| 1304 | + | ||||
| 1305 | +Include macro exclusions, matched placebo times, and permuted networks. | ||||
| 1306 | + | ||||
| 1307 | +Keep the main manuscript selective. Move secondary tables to the Internet Appendix. | ||||
| 1308 | + | ||||
| 1309 | +--- | ||||
| 1310 | + | ||||
| 1311 | +# 18. Figures required | ||||
| 1312 | + | ||||
| 1313 | +Create journal-quality figures in PDF and high-resolution PNG. | ||||
| 1314 | + | ||||
| 1315 | +## Figure 1 — Data coverage | ||||
| 1316 | + | ||||
| 1317 | +Panels may show: | ||||
| 1318 | + | ||||
| 1319 | +- number of securities by year; | ||||
| 1320 | +- number of observations by year; | ||||
| 1321 | +- median bars per stock-day; | ||||
| 1322 | +- missingness rate. | ||||
| 1323 | + | ||||
| 1324 | +## Figure 2 — Intraday seasonality | ||||
| 1325 | + | ||||
| 1326 | +Show minute-of-day patterns for: | ||||
| 1327 | + | ||||
| 1328 | +- volatility; | ||||
| 1329 | +- volume; | ||||
| 1330 | +- range; | ||||
| 1331 | +- shock incidence. | ||||
| 1332 | + | ||||
| 1333 | +## Figure 3 — Anatomy of a representative cascade | ||||
| 1334 | + | ||||
| 1335 | +A carefully selected event visualization with: | ||||
| 1336 | + | ||||
| 1337 | +- source shock; | ||||
| 1338 | +- sector response; | ||||
| 1339 | +- market breadth; | ||||
| 1340 | +- network diffusion; | ||||
| 1341 | +- confidence or placebo envelope where possible. | ||||
| 1342 | + | ||||
| 1343 | +Do not cherry-pick without a transparent selection rule. | ||||
| 1344 | + | ||||
| 1345 | +## Figure 4 — Impulse responses | ||||
| 1346 | + | ||||
| 1347 | +Local-projection responses over 1–120 minutes for: | ||||
| 1348 | + | ||||
| 1349 | +- breadth; | ||||
| 1350 | +- intensity; | ||||
| 1351 | +- signed returns; | ||||
| 1352 | +- volatility. | ||||
| 1353 | + | ||||
| 1354 | +## Figure 5 — Nonlinear propagation | ||||
| 1355 | + | ||||
| 1356 | +Plot propagation against source-shock magnitude with confidence bands. | ||||
| 1357 | + | ||||
| 1358 | +## Figure 6 — Positive-negative asymmetry | ||||
| 1359 | + | ||||
| 1360 | +Show comparable positive and negative shocks. | ||||
| 1361 | + | ||||
| 1362 | +## Figure 7 — Evolution over time | ||||
| 1363 | + | ||||
| 1364 | +Show annual or rolling estimates of propagation speed and breadth. | ||||
| 1365 | + | ||||
| 1366 | +## Figure 8 — Network position and cascade risk | ||||
| 1367 | + | ||||
| 1368 | +Show economically interpretable bins of lagged source centrality. | ||||
| 1369 | + | ||||
| 1370 | +## Figure 9 — Market-state dependence | ||||
| 1371 | + | ||||
| 1372 | +Compare calm and stressed states. | ||||
| 1373 | + | ||||
| 1374 | +## Figure 10 — Falsification evidence | ||||
| 1375 | + | ||||
| 1376 | +Real versus matched placebo and real versus permuted-network responses. | ||||
| 1377 | + | ||||
| 1378 | +--- | ||||
| 1379 | + | ||||
| 1380 | +# 19. Figure style: Journal of Finance quality | ||||
| 1381 | + | ||||
| 1382 | +The phrase “JF style” means restrained, legible, publication-quality academic graphics, not imitation of proprietary branding. | ||||
| 1383 | + | ||||
| 1384 | +Use: | ||||
| 1385 | + | ||||
| 1386 | +- vector PDF as the primary format; | ||||
| 1387 | +- embedded fonts; | ||||
| 1388 | +- white background; | ||||
| 1389 | +- minimal chart ink; | ||||
| 1390 | +- no 3D effects; | ||||
| 1391 | +- no gradients; | ||||
| 1392 | +- no decorative icons; | ||||
| 1393 | +- no unnecessary borders; | ||||
| 1394 | +- no chart titles inside the plotting region unless essential; | ||||
| 1395 | +- concise axis labels; | ||||
| 1396 | +- consistent font family and sizing; | ||||
| 1397 | +- grayscale-safe line types and markers; | ||||
| 1398 | +- colorblind-safe colors when color is needed; | ||||
| 1399 | +- direct labels where clearer than legends; | ||||
| 1400 | +- confidence bands with restrained opacity; | ||||
| 1401 | +- panel labels `(a)`, `(b)`, etc.; | ||||
| 1402 | +- identical scales across comparable panels; | ||||
| 1403 | +- economically meaningful tick marks; | ||||
| 1404 | +- no scientific notation unless unavoidable; | ||||
| 1405 | +- no excessive decimal places. | ||||
| 1406 | + | ||||
| 1407 | +Every figure must include a LaTeX note explaining: | ||||
| 1408 | + | ||||
| 1409 | +- sample; | ||||
| 1410 | +- variable definitions; | ||||
| 1411 | +- estimation method; | ||||
| 1412 | +- confidence intervals; | ||||
| 1413 | +- clustering or bootstrap; | ||||
| 1414 | +- normalization; | ||||
| 1415 | +- exclusions. | ||||
| 1416 | + | ||||
| 1417 | +Save source data for every figure as Parquet or CSV in: | ||||
| 1418 | + | ||||
| 1419 | +```text | ||||
| 1420 | +outputs/figures/data/ | ||||
| 1421 | +``` | ||||
| 1422 | + | ||||
| 1423 | +A figure must be reproducible from its source-data file without rerunning the entire empirical pipeline. | ||||
| 1424 | + | ||||
| 1425 | +--- | ||||
| 1426 | + | ||||
| 1427 | +# 20. LaTeX table style | ||||
| 1428 | + | ||||
| 1429 | +Use `booktabs`. Avoid vertical rules. Avoid excessive horizontal rules. | ||||
| 1430 | + | ||||
| 1431 | +Preferred packages: | ||||
| 1432 | + | ||||
| 1433 | +```latex | ||||
| 1434 | +\usepackage{booktabs} | ||||
| 1435 | +\usepackage{threeparttable} | ||||
| 1436 | +\usepackage{siunitx} | ||||
| 1437 | +\usepackage{adjustbox} | ||||
| 1438 | +\usepackage{longtable} | ||||
| 1439 | +\usepackage{tabularx} | ||||
| 1440 | +\usepackage{pdflscape} | ||||
| 1441 | +``` | ||||
| 1442 | + | ||||
| 1443 | +Requirements: | ||||
| 1444 | + | ||||
| 1445 | +- decimal alignment; | ||||
| 1446 | +- consistent coefficient precision; | ||||
| 1447 | +- standard errors in parentheses; | ||||
| 1448 | +- significance stars only as a secondary visual convention; | ||||
| 1449 | +- report exact or thresholded p-values where useful; | ||||
| 1450 | +- clearly label fixed effects; | ||||
| 1451 | +- clearly label clustering; | ||||
| 1452 | +- include sample size; | ||||
| 1453 | +- include within or adjusted \(R^2\) as appropriate; | ||||
| 1454 | +- include dependent-variable mean when informative; | ||||
| 1455 | +- include economic magnitude; | ||||
| 1456 | +- use clear panel headings; | ||||
| 1457 | +- use detailed table notes; | ||||
| 1458 | +- avoid shrinking text below readability. | ||||
| 1459 | + | ||||
| 1460 | +Do not use stars as the main argument. Emphasize coefficient magnitude, confidence intervals, and economic interpretation. | ||||
| 1461 | + | ||||
| 1462 | +Generate each table in two forms: | ||||
| 1463 | + | ||||
| 1464 | +1. standalone `.tex`; | ||||
| 1465 | +2. machine-readable `.csv` or `.parquet`. | ||||
| 1466 | + | ||||
| 1467 | +All table numbers must come directly from stored estimation objects. | ||||
| 1468 | + | ||||
| 1469 | +--- | ||||
| 1470 | + | ||||
| 1471 | +# 21. Literature review standard | ||||
| 1472 | + | ||||
| 1473 | +The literature review must be comprehensive, current, accurate, and organized around the paper’s contribution. It must not be a list of summaries. | ||||
| 1474 | + | ||||
| 1475 | +## 21.1 Literature streams | ||||
| 1476 | + | ||||
| 1477 | +Build a literature map covering at least: | ||||
| 1478 | + | ||||
| 1479 | +1. market liquidity and liquidity risk; | ||||
| 1480 | +2. commonality in liquidity; | ||||
| 1481 | +3. market microstructure and price discovery; | ||||
| 1482 | +4. high-frequency trading and algorithmic trading; | ||||
| 1483 | +5. market fragility and flash events; | ||||
| 1484 | +6. cross-asset price impact and cross-impact; | ||||
| 1485 | +7. volatility spillovers and contagion networks; | ||||
| 1486 | +8. lead-lag relationships; | ||||
| 1487 | +9. intraday jumps; | ||||
| 1488 | +10. Hawkes processes and self-excitation; | ||||
| 1489 | +11. factor models for high-frequency returns; | ||||
| 1490 | +12. electronic-market design and fragmentation; | ||||
| 1491 | +13. ETF, passive, and portfolio-trading effects; | ||||
| 1492 | +14. systemic risk and network centrality; | ||||
| 1493 | +15. machine learning in market microstructure; | ||||
| 1494 | +16. measurement using OHLCV versus trades and quotes. | ||||
| 1495 | + | ||||
| 1496 | +## 21.2 Source quality hierarchy | ||||
| 1497 | + | ||||
| 1498 | +Prioritize: | ||||
| 1499 | + | ||||
| 1500 | +1. published articles in leading finance, economics, econometrics, and statistics journals; | ||||
| 1501 | +2. authoritative working papers from NBER, CEPR, central banks, BIS, and established scholars; | ||||
| 1502 | +3. official exchange, SEC, Federal Reserve, and regulatory documents; | ||||
| 1503 | +4. recent working papers only when directly relevant and clearly labeled as unpublished. | ||||
| 1504 | + | ||||
| 1505 | +Do not rely on blogs, generic websites, generated summaries, or low-quality outlets for core claims. | ||||
| 1506 | + | ||||
| 1507 | +## 21.3 Citation verification | ||||
| 1508 | + | ||||
| 1509 | +For every cited work: | ||||
| 1510 | + | ||||
| 1511 | +- verify title; | ||||
| 1512 | +- verify authors; | ||||
| 1513 | +- verify year; | ||||
| 1514 | +- verify journal or working-paper series; | ||||
| 1515 | +- verify volume, issue, and pages where applicable; | ||||
| 1516 | +- verify DOI where available; | ||||
| 1517 | +- verify that the paper actually supports the sentence; | ||||
| 1518 | +- save the source and citation metadata; | ||||
| 1519 | +- never cite a work based only on another paper’s bibliography. | ||||
| 1520 | + | ||||
| 1521 | +Maintain `docs/LITERATURE_MAP.md` with columns: | ||||
| 1522 | + | ||||
| 1523 | +- citation key; | ||||
| 1524 | +- full citation; | ||||
| 1525 | +- literature stream; | ||||
| 1526 | +- research question; | ||||
| 1527 | +- data; | ||||
| 1528 | +- frequency; | ||||
| 1529 | +- identification; | ||||
| 1530 | +- main result; | ||||
| 1531 | +- relevance; | ||||
| 1532 | +- difference from our paper; | ||||
| 1533 | +- verified source; | ||||
| 1534 | +- verification date. | ||||
| 1535 | + | ||||
| 1536 | +## 21.4 Literature review argument | ||||
| 1537 | + | ||||
| 1538 | +The review should establish: | ||||
| 1539 | + | ||||
| 1540 | +1. liquidity and volatility exhibit common components; | ||||
| 1541 | +2. shocks can transmit across assets through information and trading channels; | ||||
| 1542 | +3. high-frequency market structure may improve normal-times efficiency while creating tail fragility; | ||||
| 1543 | +4. prior work often studies limited instruments, shorter samples, quotes/order books, particular episodes, or lower-dimensional networks; | ||||
| 1544 | +5. the present paper contributes a long historical, broad cross-section of minute-level U.S. equity data; | ||||
| 1545 | +6. OHLCV breadth comes with measurement limitations; | ||||
| 1546 | +7. the paper’s novelty lies in the joint analysis of speed, breadth, persistence, asymmetry, time evolution, and network conditioning. | ||||
| 1547 | + | ||||
| 1548 | +Do not overclaim uniqueness until a documented literature search confirms it. | ||||
| 1549 | + | ||||
| 1550 | +--- | ||||
| 1551 | + | ||||
| 1552 | +# 22. Paper outline | ||||
| 1553 | + | ||||
| 1554 | +The paper must be written in English. | ||||
| 1555 | + | ||||
| 1556 | +## 22.1 Abstract | ||||
| 1557 | + | ||||
| 1558 | +Target approximately 120–180 words unless the current submission rules require otherwise. | ||||
| 1559 | + | ||||
| 1560 | +The abstract must contain: | ||||
| 1561 | + | ||||
| 1562 | +1. question; | ||||
| 1563 | +2. data; | ||||
| 1564 | +3. method; | ||||
| 1565 | +4. central result; | ||||
| 1566 | +5. mechanism; | ||||
| 1567 | +6. implication. | ||||
| 1568 | + | ||||
| 1569 | +Do not include vague claims such as “significant implications.” State the economic fact. | ||||
| 1570 | + | ||||
| 1571 | +## 22.2 Introduction | ||||
| 1572 | + | ||||
| 1573 | +The introduction should be approximately 4–6 manuscript pages and follow this logic: | ||||
| 1574 | + | ||||
| 1575 | +### Paragraph 1 — Economic problem | ||||
| 1576 | +Explain why intraday propagation matters for price discovery, liquidity, execution, and systemic stability. | ||||
| 1577 | + | ||||
| 1578 | +### Paragraph 2 — Tension | ||||
| 1579 | +Present the core tension: faster and more liquid markets may absorb ordinary information efficiently but transmit extreme shocks rapidly. | ||||
| 1580 | + | ||||
| 1581 | +### Paragraph 3 — Research question | ||||
| 1582 | +State exactly what the paper asks. | ||||
| 1583 | + | ||||
| 1584 | +### Paragraph 4 — Data and empirical setting | ||||
| 1585 | +Describe the broad minute-level panel, while flagging that validation determines the final sample. | ||||
| 1586 | + | ||||
| 1587 | +### Paragraphs 5–7 — Main findings | ||||
| 1588 | +Present only verified findings, including economic magnitudes and uncertainty. | ||||
| 1589 | + | ||||
| 1590 | +### Paragraph 8 — Identification | ||||
| 1591 | +Explain how the paper distinguishes propagation from common information. | ||||
| 1592 | + | ||||
| 1593 | +### Paragraph 9 — Mechanisms | ||||
| 1594 | +Summarize network, market-state, and asymmetry evidence. | ||||
| 1595 | + | ||||
| 1596 | +### Paragraphs 10–12 — Contributions | ||||
| 1597 | +State contributions relative to specific literature streams. | ||||
| 1598 | + | ||||
| 1599 | +### Final paragraph — Road map | ||||
| 1600 | +Keep it brief. | ||||
| 1601 | + | ||||
| 1602 | +The introduction must not read like a technical report. It must build an economic argument. | ||||
| 1603 | + | ||||
| 1604 | +## 22.3 Literature review | ||||
| 1605 | + | ||||
| 1606 | +Integrate literature with hypotheses and contributions. Avoid a long disconnected catalog. | ||||
| 1607 | + | ||||
| 1608 | +## 22.4 Data | ||||
| 1609 | + | ||||
| 1610 | +Explain: | ||||
| 1611 | + | ||||
| 1612 | +- provenance; | ||||
| 1613 | +- raw structure; | ||||
| 1614 | +- coverage; | ||||
| 1615 | +- audit; | ||||
| 1616 | +- filters; | ||||
| 1617 | +- timestamp convention; | ||||
| 1618 | +- corporate-action handling; | ||||
| 1619 | +- security identity; | ||||
| 1620 | +- survivorship concerns; | ||||
| 1621 | +- descriptive statistics; | ||||
| 1622 | +- limitations. | ||||
| 1623 | + | ||||
| 1624 | +## 22.5 Measurement | ||||
| 1625 | + | ||||
| 1626 | +Define: | ||||
| 1627 | + | ||||
| 1628 | +- residual shocks; | ||||
| 1629 | +- propagation outcomes; | ||||
| 1630 | +- networks; | ||||
| 1631 | +- market states; | ||||
| 1632 | +- centrality; | ||||
| 1633 | +- cascade thresholds. | ||||
| 1634 | + | ||||
| 1635 | +## 22.6 Empirical design | ||||
| 1636 | + | ||||
| 1637 | +Explain: | ||||
| 1638 | + | ||||
| 1639 | +- local projections; | ||||
| 1640 | +- event-study design; | ||||
| 1641 | +- fixed effects; | ||||
| 1642 | +- inference; | ||||
| 1643 | +- timing; | ||||
| 1644 | +- identification assumptions; | ||||
| 1645 | +- threats. | ||||
| 1646 | + | ||||
| 1647 | +## 22.7 Results | ||||
| 1648 | + | ||||
| 1649 | +Organize by economic question, not by code execution order. | ||||
| 1650 | + | ||||
| 1651 | +Suggested sequence: | ||||
| 1652 | + | ||||
| 1653 | +1. basic propagation; | ||||
| 1654 | +2. nonlinear threshold; | ||||
| 1655 | +3. asymmetry; | ||||
| 1656 | +4. time evolution; | ||||
| 1657 | +5. network mechanism; | ||||
| 1658 | +6. market-state dependence; | ||||
| 1659 | +7. identification and placebo evidence. | ||||
| 1660 | + | ||||
| 1661 | +## 22.8 Robustness | ||||
| 1662 | + | ||||
| 1663 | +Keep the main text focused. Refer to a detailed Internet Appendix. | ||||
| 1664 | + | ||||
| 1665 | +## 22.9 Conclusion | ||||
| 1666 | + | ||||
| 1667 | +Do not merely summarize. State: | ||||
| 1668 | + | ||||
| 1669 | +- what was learned; | ||||
| 1670 | +- what remains unidentified; | ||||
| 1671 | +- implications for market design and risk monitoring; | ||||
| 1672 | +- limits of OHLCV data; | ||||
| 1673 | +- future work with quote and order-book data. | ||||
| 1674 | + | ||||
| 1675 | +--- | ||||
| 1676 | + | ||||
| 1677 | +# 23. Writing standards | ||||
| 1678 | + | ||||
| 1679 | +The paper must read like a finance paper, not AI-generated prose. | ||||
| 1680 | + | ||||
| 1681 | +Use: | ||||
| 1682 | + | ||||
| 1683 | +- precise claims; | ||||
| 1684 | +- active voice where natural; | ||||
| 1685 | +- disciplined paragraphs; | ||||
| 1686 | +- explicit economic magnitudes; | ||||
| 1687 | +- clear transitions; | ||||
| 1688 | +- restrained tone; | ||||
| 1689 | +- correct terminology; | ||||
| 1690 | +- consistent notation. | ||||
| 1691 | + | ||||
| 1692 | +Avoid: | ||||
| 1693 | + | ||||
| 1694 | +- hype; | ||||
| 1695 | +- “revolutionary”; | ||||
| 1696 | +- “groundbreaking” unless quoting; | ||||
| 1697 | +- “unprecedented” without proof; | ||||
| 1698 | +- “leveraging” as filler; | ||||
| 1699 | +- “delve”; | ||||
| 1700 | +- “multifaceted”; | ||||
| 1701 | +- repeated road maps; | ||||
| 1702 | +- excessive bullet points in the manuscript; | ||||
| 1703 | +- paragraphs that merely describe tables; | ||||
| 1704 | +- causal verbs without identification; | ||||
| 1705 | +- statements that statistical significance proves importance. | ||||
| 1706 | + | ||||
| 1707 | +Every empirical paragraph should answer: | ||||
| 1708 | + | ||||
| 1709 | +1. What is estimated? | ||||
| 1710 | +2. What is the sign and magnitude? | ||||
| 1711 | +3. How uncertain is it? | ||||
| 1712 | +4. What is the economic interpretation? | ||||
| 1713 | +5. Which competing explanation remains? | ||||
| 1714 | +6. Which robustness test addresses it? | ||||
| 1715 | + | ||||
| 1716 | +--- | ||||
| 1717 | + | ||||
| 1718 | +# 24. JF submission preparation | ||||
| 1719 | + | ||||
| 1720 | +At the time of final preparation, verify the current official Journal of Finance submission instructions. | ||||
| 1721 | + | ||||
| 1722 | +The working format should conservatively use: | ||||
| 1723 | + | ||||
| 1724 | +- 12-point font; | ||||
| 1725 | +- at least 1.5 line spacing; | ||||
| 1726 | +- readable margins; | ||||
| 1727 | +- page numbers; | ||||
| 1728 | +- anonymous manuscript version; | ||||
| 1729 | +- separate title page if required; | ||||
| 1730 | +- main manuscript no longer than the current JF limit; | ||||
| 1731 | +- separate Internet Appendix; | ||||
| 1732 | +- consistent references; | ||||
| 1733 | +- tables and figures placed according to current instructions. | ||||
| 1734 | + | ||||
| 1735 | +Do not assume old formatting rules remain current. Record the date and source of the final guideline check in: | ||||
| 1736 | + | ||||
| 1737 | +```text | ||||
| 1738 | +docs/DECISION_LOG.md | ||||
| 1739 | +``` | ||||
| 1740 | + | ||||
| 1741 | +Create: | ||||
| 1742 | + | ||||
| 1743 | +```text | ||||
| 1744 | +outputs/release/ | ||||
| 1745 | +├── manuscript_anonymous.pdf | ||||
| 1746 | +├── manuscript_named.pdf | ||||
| 1747 | +├── internet_appendix.pdf | ||||
| 1748 | +├── title_page.pdf | ||||
| 1749 | +├── cover_letter.tex | ||||
| 1750 | +├── cover_letter.pdf | ||||
| 1751 | +├── source_archive.zip | ||||
| 1752 | +├── replication_manifest.json | ||||
| 1753 | +└── submission_checklist.md | ||||
| 1754 | +``` | ||||
| 1755 | + | ||||
| 1756 | +The cover letter must be factual and restrained. Do not claim acceptance probability or editorial fit without evidence. | ||||
| 1757 | + | ||||
| 1758 | +--- | ||||
| 1759 | + | ||||
| 1760 | +# 25. Main paper versus Internet Appendix | ||||
| 1761 | + | ||||
| 1762 | +## Main paper | ||||
| 1763 | + | ||||
| 1764 | +Reserve for: | ||||
| 1765 | + | ||||
| 1766 | +- core question; | ||||
| 1767 | +- central descriptive evidence; | ||||
| 1768 | +- primary identification; | ||||
| 1769 | +- main economic mechanism; | ||||
| 1770 | +- essential robustness; | ||||
| 1771 | +- clear contribution. | ||||
| 1772 | + | ||||
| 1773 | +## Internet Appendix | ||||
| 1774 | + | ||||
| 1775 | +Include: | ||||
| 1776 | + | ||||
| 1777 | +- extended data audit; | ||||
| 1778 | +- full sample-construction details; | ||||
| 1779 | +- additional variable definitions; | ||||
| 1780 | +- alternative filters; | ||||
| 1781 | +- alternative networks; | ||||
| 1782 | +- alternative thresholds; | ||||
| 1783 | +- additional event studies; | ||||
| 1784 | +- placebo distributions; | ||||
| 1785 | +- machine-learning architecture; | ||||
| 1786 | +- hyperparameters; | ||||
| 1787 | +- computational details; | ||||
| 1788 | +- additional tables and figures; | ||||
| 1789 | +- proofs or derivations; | ||||
| 1790 | +- replication details. | ||||
| 1791 | + | ||||
| 1792 | +Every appendix item must be referenced from the main paper where relevant. | ||||
| 1793 | + | ||||
| 1794 | +--- | ||||
| 1795 | + | ||||
| 1796 | +# 26. Reproducibility and provenance | ||||
| 1797 | + | ||||
| 1798 | +## 26.1 Configuration | ||||
| 1799 | + | ||||
| 1800 | +All parameters must live in versioned YAML files, not scattered through scripts. | ||||
| 1801 | + | ||||
| 1802 | +## 26.2 Random seeds | ||||
| 1803 | + | ||||
| 1804 | +Set and log seeds for: | ||||
| 1805 | + | ||||
| 1806 | +- sampling; | ||||
| 1807 | +- bootstraps; | ||||
| 1808 | +- permutations; | ||||
| 1809 | +- machine learning; | ||||
| 1810 | +- graph estimation; | ||||
| 1811 | +- simulations. | ||||
| 1812 | + | ||||
| 1813 | +## 26.3 Versioning | ||||
| 1814 | + | ||||
| 1815 | +Record: | ||||
| 1816 | + | ||||
| 1817 | +- Git commit; | ||||
| 1818 | +- Python version; | ||||
| 1819 | +- package versions; | ||||
| 1820 | +- OS; | ||||
| 1821 | +- hardware; | ||||
| 1822 | +- dataset revision; | ||||
| 1823 | +- external-data revision; | ||||
| 1824 | +- command line; | ||||
| 1825 | +- start and end time. | ||||
| 1826 | + | ||||
| 1827 | +## 26.4 Data lineage | ||||
| 1828 | + | ||||
| 1829 | +Each processed file must record: | ||||
| 1830 | + | ||||
| 1831 | +- parent inputs; | ||||
| 1832 | +- transformation version; | ||||
| 1833 | +- filters; | ||||
| 1834 | +- row counts before and after; | ||||
| 1835 | +- creation timestamp; | ||||
| 1836 | +- code commit. | ||||
| 1837 | + | ||||
| 1838 | +## 26.5 No manual numerical edits | ||||
| 1839 | + | ||||
| 1840 | +LaTeX tables, abstract numbers, introduction magnitudes, and conclusion numbers must be populated from a central results registry such as: | ||||
| 1841 | + | ||||
| 1842 | +```text | ||||
| 1843 | +outputs/estimates/results_registry.json | ||||
| 1844 | +``` | ||||
| 1845 | + | ||||
| 1846 | +Implement macros such as: | ||||
| 1847 | + | ||||
| 1848 | +```latex | ||||
| 1849 | +\newcommand{\MainBreadthEffect}{...} | ||||
| 1850 | +``` | ||||
| 1851 | + | ||||
| 1852 | +generated automatically from verified outputs. | ||||
| 1853 | + | ||||
| 1854 | +--- | ||||
| 1855 | + | ||||
| 1856 | +# 27. Compute strategy for a cluster | ||||
| 1857 | + | ||||
| 1858 | +The pipeline must be scalable but safe. | ||||
| 1859 | + | ||||
| 1860 | +## 27.1 Preferred data tools | ||||
| 1861 | + | ||||
| 1862 | +Consider: | ||||
| 1863 | + | ||||
| 1864 | +- PyArrow; | ||||
| 1865 | +- Polars lazy execution; | ||||
| 1866 | +- DuckDB; | ||||
| 1867 | +- Dask or Ray only where they add value; | ||||
| 1868 | +- partitioned Parquet; | ||||
| 1869 | +- predicate pushdown; | ||||
| 1870 | +- memory-mapped reads; | ||||
| 1871 | +- streaming aggregations. | ||||
| 1872 | + | ||||
| 1873 | +Avoid loading the full dataset into RAM. | ||||
| 1874 | + | ||||
| 1875 | +## 27.2 Partitioning | ||||
| 1876 | + | ||||
| 1877 | +Partition processed data by a combination of: | ||||
| 1878 | + | ||||
| 1879 | +- year; | ||||
| 1880 | +- month; | ||||
| 1881 | +- trading date; | ||||
| 1882 | +- symbol bucket. | ||||
| 1883 | + | ||||
| 1884 | +Select partitions based on dominant query patterns. | ||||
| 1885 | + | ||||
| 1886 | +## 27.3 Distributed jobs | ||||
| 1887 | + | ||||
| 1888 | +Every distributed task must: | ||||
| 1889 | + | ||||
| 1890 | +- be idempotent; | ||||
| 1891 | +- write to temporary paths; | ||||
| 1892 | +- atomically rename on success; | ||||
| 1893 | +- save checkpoints; | ||||
| 1894 | +- avoid multiple nodes writing the same final file; | ||||
| 1895 | +- emit structured logs; | ||||
| 1896 | +- support retry; | ||||
| 1897 | +- validate output before success. | ||||
| 1898 | + | ||||
| 1899 | +## 27.4 Resource benchmarking | ||||
| 1900 | + | ||||
| 1901 | +Before a full run: | ||||
| 1902 | + | ||||
| 1903 | +1. benchmark one month; | ||||
| 1904 | +2. benchmark one year; | ||||
| 1905 | +3. estimate CPU hours; | ||||
| 1906 | +4. estimate memory; | ||||
| 1907 | +5. estimate temporary storage; | ||||
| 1908 | +6. estimate final storage; | ||||
| 1909 | +7. record in `docs/COMPUTE_LOG.md`. | ||||
| 1910 | + | ||||
| 1911 | +Optimization must not change estimands or silently alter precision. | ||||
| 1912 | + | ||||
| 1913 | +--- | ||||
| 1914 | + | ||||
| 1915 | +# 28. Testing and validation | ||||
| 1916 | + | ||||
| 1917 | +## 28.1 Unit tests | ||||
| 1918 | + | ||||
| 1919 | +Test: | ||||
| 1920 | + | ||||
| 1921 | +- timestamp conversion; | ||||
| 1922 | +- session assignment; | ||||
| 1923 | +- return calculation; | ||||
| 1924 | +- shock detection; | ||||
| 1925 | +- lag discipline; | ||||
| 1926 | +- no future-data leakage; | ||||
| 1927 | +- network-window cutoffs; | ||||
| 1928 | +- breadth denominator; | ||||
| 1929 | +- session-boundary horizons; | ||||
| 1930 | +- table formatting. | ||||
| 1931 | + | ||||
| 1932 | +## 28.2 Synthetic-data tests | ||||
| 1933 | + | ||||
| 1934 | +Generate small synthetic panels with known: | ||||
| 1935 | + | ||||
| 1936 | +- common shocks; | ||||
| 1937 | +- idiosyncratic shocks; | ||||
| 1938 | +- directed propagation; | ||||
| 1939 | +- no propagation; | ||||
| 1940 | +- positive-negative asymmetry; | ||||
| 1941 | +- missing bars; | ||||
| 1942 | +- split-like jumps. | ||||
| 1943 | + | ||||
| 1944 | +Confirm that the pipeline recovers the intended patterns and rejects false ones. | ||||
| 1945 | + | ||||
| 1946 | +## 28.3 Release validation | ||||
| 1947 | + | ||||
| 1948 | +The release script must fail if: | ||||
| 1949 | + | ||||
| 1950 | +- a table references a missing result; | ||||
| 1951 | +- a figure is missing source data; | ||||
| 1952 | +- LaTeX does not compile; | ||||
| 1953 | +- citations are unresolved; | ||||
| 1954 | +- labels are duplicated; | ||||
| 1955 | +- page count exceeds the current target; | ||||
| 1956 | +- anonymous PDF contains author-identifying text; | ||||
| 1957 | +- manuscript claims disagree with the results registry; | ||||
| 1958 | +- data revision is not pinned; | ||||
| 1959 | +- tests fail. | ||||
| 1960 | + | ||||
| 1961 | +--- | ||||
| 1962 | + | ||||
| 1963 | +# 29. Decision log | ||||
| 1964 | + | ||||
| 1965 | +Maintain `docs/DECISION_LOG.md`. | ||||
| 1966 | + | ||||
| 1967 | +For every major choice, record: | ||||
| 1968 | + | ||||
| 1969 | +- date; | ||||
| 1970 | +- decision; | ||||
| 1971 | +- alternatives considered; | ||||
| 1972 | +- empirical reason; | ||||
| 1973 | +- theoretical reason; | ||||
| 1974 | +- effect on interpretation; | ||||
| 1975 | +- whether pre-specified or data-driven; | ||||
| 1976 | +- code/config reference. | ||||
| 1977 | + | ||||
| 1978 | +Important decisions include: | ||||
| 1979 | + | ||||
| 1980 | +- timestamp convention; | ||||
| 1981 | +- regular-session definition; | ||||
| 1982 | +- security filters; | ||||
| 1983 | +- shock threshold; | ||||
| 1984 | +- network window; | ||||
| 1985 | +- factor model; | ||||
| 1986 | +- clustering; | ||||
| 1987 | +- periodization; | ||||
| 1988 | +- figure selection; | ||||
| 1989 | +- main versus appendix placement. | ||||
| 1990 | + | ||||
| 1991 | +--- | ||||
| 1992 | + | ||||
| 1993 | +# 30. Minimum deliverables for the first phase | ||||
| 1994 | + | ||||
| 1995 | +The first phase is complete only when all the following exist. | ||||
| 1996 | + | ||||
| 1997 | +## Data acquisition | ||||
| 1998 | + | ||||
| 1999 | +- [ ] repository metadata report; | ||||
| 2000 | +- [ ] pinned dataset revision; | ||||
| 2001 | +- [ ] storage estimate; | ||||
| 2002 | +- [ ] resumable downloader; | ||||
| 2003 | +- [ ] raw manifest; | ||||
| 2004 | +- [ ] checksum verification; | ||||
| 2005 | +- [ ] three-month pilot sample; | ||||
| 2006 | +- [ ] full-download plan. | ||||
| 2007 | + | ||||
| 2008 | +## Audit | ||||
| 2009 | + | ||||
| 2010 | +- [ ] schema report; | ||||
| 2011 | +- [ ] timestamp report; | ||||
| 2012 | +- [ ] calendar report; | ||||
| 2013 | +- [ ] OHLC validity report; | ||||
| 2014 | +- [ ] duplicate report; | ||||
| 2015 | +- [ ] missingness report; | ||||
| 2016 | +- [ ] corporate-action diagnostic; | ||||
| 2017 | +- [ ] security-universe diagnostic; | ||||
| 2018 | +- [ ] survivorship assessment; | ||||
| 2019 | +- [ ] limitations memo. | ||||
| 2020 | + | ||||
| 2021 | +## Prototype analysis | ||||
| 2022 | + | ||||
| 2023 | +- [ ] clean pilot panel; | ||||
| 2024 | +- [ ] intraday seasonality figure; | ||||
| 2025 | +- [ ] sample-coverage figure; | ||||
| 2026 | +- [ ] preliminary shock definition; | ||||
| 2027 | +- [ ] preliminary cascade measure; | ||||
| 2028 | +- [ ] one transparent baseline regression; | ||||
| 2029 | +- [ ] one placebo test; | ||||
| 2030 | +- [ ] one LaTeX summary-statistics table; | ||||
| 2031 | +- [ ] one LaTeX baseline-results table. | ||||
| 2032 | + | ||||
| 2033 | +## Paper infrastructure | ||||
| 2034 | + | ||||
| 2035 | +- [ ] compiling `main.tex`; | ||||
| 2036 | +- [ ] compiling Internet Appendix; | ||||
| 2037 | +- [ ] verified bibliography workflow; | ||||
| 2038 | +- [ ] literature map; | ||||
| 2039 | +- [ ] introduction outline; | ||||
| 2040 | +- [ ] data-section draft based only on verified facts; | ||||
| 2041 | +- [ ] automated figure and table inclusion. | ||||
| 2042 | + | ||||
| 2043 | +--- | ||||
| 2044 | + | ||||
| 2045 | +# 31. Stop conditions | ||||
| 2046 | + | ||||
| 2047 | +Stop and write a diagnostic report rather than proceeding if: | ||||
| 2048 | + | ||||
| 2049 | +- timestamps cannot be interpreted reliably; | ||||
| 2050 | +- OHLC values are extensively inconsistent; | ||||
| 2051 | +- split adjustments cannot be handled sufficiently for return analysis; | ||||
| 2052 | +- the universe is severely survivorship-biased and cannot be characterized; | ||||
| 2053 | +- historical coverage is too sparse for the claimed design; | ||||
| 2054 | +- symbol identity errors dominate long-run comparisons; | ||||
| 2055 | +- data licensing prevents the intended use; | ||||
| 2056 | +- results depend on undocumented transformations; | ||||
| 2057 | +- common-news contamination cannot be separated even approximately; | ||||
| 2058 | +- inference is computationally impossible at the intended unit without changing the design. | ||||
| 2059 | + | ||||
| 2060 | +A rigorous negative assessment is preferable to a polished but invalid paper. | ||||
| 2061 | + | ||||
| 2062 | +--- | ||||
| 2063 | + | ||||
| 2064 | +# 32. Commands and workflow | ||||
| 2065 | + | ||||
| 2066 | +Create a Makefile with targets similar to: | ||||
| 2067 | + | ||||
| 2068 | +```make | ||||
| 2069 | +probe | ||||
| 2070 | +download-pilot | ||||
| 2071 | +audit-pilot | ||||
| 2072 | +download-full | ||||
| 2073 | +verify-data | ||||
| 2074 | +build-panel | ||||
| 2075 | +build-features | ||||
| 2076 | +detect-shocks | ||||
| 2077 | +estimate-networks | ||||
| 2078 | +estimate-baseline | ||||
| 2079 | +estimate-events | ||||
| 2080 | +run-placebos | ||||
| 2081 | +run-robustness | ||||
| 2082 | +figures | ||||
| 2083 | +tables | ||||
| 2084 | +paper | ||||
| 2085 | +appendix | ||||
| 2086 | +validate | ||||
| 2087 | +release | ||||
| 2088 | +``` | ||||
| 2089 | + | ||||
| 2090 | +A complete reproducible run should ultimately be possible through: | ||||
| 2091 | + | ||||
| 2092 | +```bash | ||||
| 2093 | +make release | ||||
| 2094 | +``` | ||||
| 2095 | + | ||||
| 2096 | +Do not run `make release` until the pilot audit and full-data checks pass. | ||||
| 2097 | + | ||||
| 2098 | +--- | ||||
| 2099 | + | ||||
| 2100 | +# 33. Immediate actions | ||||
| 2101 | + | ||||
| 2102 | +Begin now with the following actions, in order: | ||||
| 2103 | + | ||||
| 2104 | +1. Create the project directory structure. | ||||
| 2105 | +2. Initialize environment and dependency files. | ||||
| 2106 | +3. Inspect the Hugging Face dataset repository without downloading all files. | ||||
| 2107 | +4. Pin the exact dataset revision. | ||||
| 2108 | +5. Create a repository-level file inventory. | ||||
| 2109 | +6. Estimate total download and processed-storage needs. | ||||
| 2110 | +7. Download three strategically selected monthly files: | ||||
| 2111 | + - one early month; | ||||
| 2112 | + - one middle-sample month; | ||||
| 2113 | + - one recent month. | ||||
| 2114 | +8. Audit schema and timestamps. | ||||
| 2115 | +9. Produce `docs/DATA_AUDIT.md`. | ||||
| 2116 | +10. Produce `docs/LIMITATIONS.md`. | ||||
| 2117 | +11. Produce pilot coverage and intraday-seasonality figures. | ||||
| 2118 | +12. Produce one summary-statistics LaTeX table. | ||||
| 2119 | +13. Build `docs/LITERATURE_MAP.md` and begin a verified literature search. | ||||
| 2120 | +14. Create a compiling LaTeX manuscript skeleton. | ||||
| 2121 | +15. Draft only the portions of the Data section supported by the audit. | ||||
| 2122 | +16. Report blockers and proposed solutions before launching the full download. | ||||
| 2123 | + | ||||
| 2124 | +At the end of each major stage, produce: | ||||
| 2125 | + | ||||
| 2126 | +```text | ||||
| 2127 | +STATUS.md | ||||
| 2128 | +``` | ||||
| 2129 | + | ||||
| 2130 | +with: | ||||
| 2131 | + | ||||
| 2132 | +- completed work; | ||||
| 2133 | +- generated files; | ||||
| 2134 | +- key findings; | ||||
| 2135 | +- quality-control results; | ||||
| 2136 | +- unresolved issues; | ||||
| 2137 | +- next commands; | ||||
| 2138 | +- decisions requiring attention. | ||||
| 2139 | + | ||||
| 2140 | +Do not ask for confirmation for routine implementation choices. Make the most defensible choice, record it, and continue. Escalate only issues that materially alter the research question, data legality, identification, or interpretation. | ||||
| 2141 | + | ||||
| 2142 | +--- | ||||
| 2143 | + | ||||
| 2144 | +# 34. Final quality criterion | ||||
| 2145 | + | ||||
| 2146 | +The paper is not “ready for JF” merely because it compiles or contains many analyses. | ||||
| 2147 | + | ||||
| 2148 | +It is ready for serious submission consideration only if: | ||||
| 2149 | + | ||||
| 2150 | +- the data are credible and fully audited; | ||||
| 2151 | +- the paper documents a new and economically important fact; | ||||
| 2152 | +- propagation is separated as far as possible from common information; | ||||
| 2153 | +- magnitudes are economically meaningful; | ||||
| 2154 | +- results survive serious falsification tests; | ||||
| 2155 | +- the mechanism is coherent; | ||||
| 2156 | +- the literature positioning is accurate; | ||||
| 2157 | +- the writing is disciplined; | ||||
| 2158 | +- the figures and tables are publication quality; | ||||
| 2159 | +- all claims are reproducible; | ||||
| 2160 | +- limitations are explicit; | ||||
| 2161 | +- the main paper is focused; | ||||
| 2162 | +- the Internet Appendix is complete; | ||||
| 2163 | +- no result has been fabricated, selectively hidden, or overstated. | ||||
| 2164 | + | ||||
| 2165 | +The standard is not to make the paper appear publishable. The standard is to determine honestly whether the evidence supports a contribution worthy of a top finance journal and, if it does, to present that contribution with maximum clarity and rigor. | ||||
added
research/corpus/WP15_PROMPT_PROMPT_INITIAL_CLAUDE.md
+2165 −0
@@ -0,0 +1,2165 @@ | |||||
| 1 | +# CLAUDE.md — Intraday Market Fragility Research Program | ||||
| 2 | + | ||||
| 3 | +## 0. Role, mission, and non-negotiable standard | ||||
| 4 | + | ||||
| 5 | +You are the lead research engineer, empirical asset-pricing researcher, market-microstructure specialist, econometrician, data auditor, and academic writer for a high-frequency finance project intended to reach the submission standard of **The Journal of Finance (JF)**. | ||||
| 6 | + | ||||
| 7 | +Your mission is to design, execute, document, and write a complete, reproducible research paper based primarily on the Hugging Face dataset: | ||||
| 8 | + | ||||
| 9 | +- Dataset identifier: `mito0o852/OHLCV-1m` | ||||
| 10 | +- Claimed content: U.S. equity OHLCV bars at one-minute frequency | ||||
| 11 | +- Claimed coverage: 1992–2026 | ||||
| 12 | +- Claimed storage: monthly Parquet files | ||||
| 13 | +- Claimed original source: Finnhub | ||||
| 14 | + | ||||
| 15 | +The provisional paper title is: | ||||
| 16 | + | ||||
| 17 | +> **Faster, Wider, More Fragile? The Evolution of Intraday Shock Propagation in U.S. Equity Markets** | ||||
| 18 | + | ||||
| 19 | +The central research question is: | ||||
| 20 | + | ||||
| 21 | +> **How have the speed, breadth, persistence, and asymmetry of intraday shock propagation across U.S. equities evolved over the past three decades, and under which market conditions does an initially idiosyncratic shock become sectoral or market-wide?** | ||||
| 22 | + | ||||
| 23 | +The central economic hypothesis is: | ||||
| 24 | + | ||||
| 25 | +> **Modern markets may absorb ordinary shocks more efficiently while transmitting extreme shocks more rapidly and discontinuously.** | ||||
| 26 | + | ||||
| 27 | +This is not a generic machine-learning forecasting project. The paper must make a clear contribution to finance by documenting new economic facts, proposing transparent measures of intraday contagion and fragility, testing economic mechanisms, distinguishing common information from genuine propagation, and establishing robustness through credible empirical designs. | ||||
| 28 | + | ||||
| 29 | +The final output must be: | ||||
| 30 | + | ||||
| 31 | +1. fully reproducible; | ||||
| 32 | +2. empirically honest; | ||||
| 33 | +3. economically motivated; | ||||
| 34 | +4. methodologically rigorous; | ||||
| 35 | +5. written in polished academic English; | ||||
| 36 | +6. formatted as a complete LaTeX submission package; | ||||
| 37 | +7. accompanied by a detailed Internet Appendix; | ||||
| 38 | +8. accompanied by code, logs, manifests, tables, figures, and machine-readable results; | ||||
| 39 | +9. prepared to the standard expected in a top finance journal; | ||||
| 40 | +10. explicit about every limitation imposed by OHLCV data. | ||||
| 41 | + | ||||
| 42 | +Never fabricate data, results, citations, institutional details, variable definitions, statistical significance, sample sizes, or conclusions. Never write a result in the paper before it has been generated and verified from a saved machine-readable output. | ||||
| 43 | + | ||||
| 44 | +--- | ||||
| 45 | + | ||||
| 46 | +# 1. Research philosophy | ||||
| 47 | + | ||||
| 48 | +## 1.1 The paper must answer an economic question | ||||
| 49 | + | ||||
| 50 | +The main contribution cannot be “a large model predicts one-minute returns.” Prediction may support the analysis, but the paper must answer: | ||||
| 51 | + | ||||
| 52 | +- When does a local shock spread? | ||||
| 53 | +- How rapidly does it spread? | ||||
| 54 | +- How broadly does it spread? | ||||
| 55 | +- How persistent is the propagation? | ||||
| 56 | +- Is propagation asymmetric for negative and positive shocks? | ||||
| 57 | +- Has propagation changed over time? | ||||
| 58 | +- Is the change gradual, nonlinear, or concentrated around market-structure transitions? | ||||
| 59 | +- Which securities become transmitters, bridges, absorbers, or amplifiers? | ||||
| 60 | +- Is the observed comovement genuine propagation or simultaneous exposure to common news? | ||||
| 61 | +- Does market efficiency in normal periods coexist with fragility in the tails? | ||||
| 62 | + | ||||
| 63 | +## 1.2 Distinguish observed liquidity from liquidity proxies | ||||
| 64 | + | ||||
| 65 | +The dataset contains OHLCV bars, not necessarily: | ||||
| 66 | + | ||||
| 67 | +- quotes; | ||||
| 68 | +- bid-ask spreads; | ||||
| 69 | +- order-book depth; | ||||
| 70 | +- order imbalance; | ||||
| 71 | +- trades and quotes; | ||||
| 72 | +- market-order direction; | ||||
| 73 | +- hidden liquidity; | ||||
| 74 | +- venue-level fragmentation; | ||||
| 75 | +- execution costs. | ||||
| 76 | + | ||||
| 77 | +Therefore: | ||||
| 78 | + | ||||
| 79 | +- Do not claim to observe liquidity directly. | ||||
| 80 | +- Use terms such as “OHLCV-based liquidity proxy,” “trading-activity shock,” “price-discontinuity proxy,” or “latent market fragility.” | ||||
| 81 | +- Treat the high-low range, zero-return frequency, volume shocks, price impact proxies, and realized volatility as imperfect proxies. | ||||
| 82 | +- Include a dedicated limitations section. | ||||
| 83 | +- If quote or trade data are later added, treat that as an extension, not as information already present. | ||||
| 84 | + | ||||
| 85 | +## 1.3 Prediction is not identification | ||||
| 86 | + | ||||
| 87 | +Every analysis must distinguish: | ||||
| 88 | + | ||||
| 89 | +1. contemporaneous co-movement; | ||||
| 90 | +2. predictive lead-lag; | ||||
| 91 | +3. propagation conditional on observed information; | ||||
| 92 | +4. causal propagation; | ||||
| 93 | +5. structural counterfactual simulation. | ||||
| 94 | + | ||||
| 95 | +Do not use causal language unless the design supports it. Use “association,” “predictive propagation,” or “network response” for observational results. Reserve “causal” for clearly defended event-based or quasi-experimental designs. | ||||
| 96 | + | ||||
| 97 | +--- | ||||
| 98 | + | ||||
| 99 | +# 2. Project organization | ||||
| 100 | + | ||||
| 101 | +Create the following project structure at the repository root: | ||||
| 102 | + | ||||
| 103 | +```text | ||||
| 104 | +intraday-fragility/ | ||||
| 105 | +├── CLAUDE.md | ||||
| 106 | +├── README.md | ||||
| 107 | +├── LICENSE | ||||
| 108 | +├── CITATION.cff | ||||
| 109 | +├── pyproject.toml | ||||
| 110 | +├── uv.lock | ||||
| 111 | +├── environment.yml | ||||
| 112 | +├── .env.example | ||||
| 113 | +├── .gitignore | ||||
| 114 | +├── Makefile | ||||
| 115 | +├── config/ | ||||
| 116 | +│ ├── base.yaml | ||||
| 117 | +│ ├── paths.yaml | ||||
| 118 | +│ ├── sample_filters.yaml | ||||
| 119 | +│ ├── shock_definitions.yaml | ||||
| 120 | +│ ├── models.yaml | ||||
| 121 | +│ ├── figures.yaml | ||||
| 122 | +│ └── tables.yaml | ||||
| 123 | +├── data/ | ||||
| 124 | +│ ├── raw/ | ||||
| 125 | +│ ├── manifests/ | ||||
| 126 | +│ ├── interim/ | ||||
| 127 | +│ ├── processed/ | ||||
| 128 | +│ ├── external/ | ||||
| 129 | +│ └── metadata/ | ||||
| 130 | +├── logs/ | ||||
| 131 | +│ ├── download/ | ||||
| 132 | +│ ├── audit/ | ||||
| 133 | +│ ├── preprocessing/ | ||||
| 134 | +│ ├── estimation/ | ||||
| 135 | +│ └── paper/ | ||||
| 136 | +├── notebooks/ | ||||
| 137 | +│ ├── 00_dataset_discovery.ipynb | ||||
| 138 | +│ ├── 01_small_sample_audit.ipynb | ||||
| 139 | +│ ├── 02_intraday_patterns.ipynb | ||||
| 140 | +│ └── 03_prototype_results.ipynb | ||||
| 141 | +├── src/ | ||||
| 142 | +│ └── intraday_fragility/ | ||||
| 143 | +│ ├── __init__.py | ||||
| 144 | +│ ├── cli.py | ||||
| 145 | +│ ├── paths.py | ||||
| 146 | +│ ├── logging_utils.py | ||||
| 147 | +│ ├── download.py | ||||
| 148 | +│ ├── manifest.py | ||||
| 149 | +│ ├── schema.py | ||||
| 150 | +│ ├── calendars.py | ||||
| 151 | +│ ├── corporate_actions.py | ||||
| 152 | +│ ├── identifiers.py | ||||
| 153 | +│ ├── universe.py | ||||
| 154 | +│ ├── cleaning.py | ||||
| 155 | +│ ├── features.py | ||||
| 156 | +│ ├── shocks.py | ||||
| 157 | +│ ├── networks.py | ||||
| 158 | +│ ├── contagion.py | ||||
| 159 | +│ ├── econometrics.py | ||||
| 160 | +│ ├── inference.py | ||||
| 161 | +│ ├── robustness.py | ||||
| 162 | +│ ├── simulations.py | ||||
| 163 | +│ ├── figures.py | ||||
| 164 | +│ ├── tables.py | ||||
| 165 | +│ ├── latex.py | ||||
| 166 | +│ └── validation.py | ||||
| 167 | +├── scripts/ | ||||
| 168 | +│ ├── 00_probe_hf_dataset.py | ||||
| 169 | +│ ├── 01_download_hf_data.py | ||||
| 170 | +│ ├── 02_build_raw_manifest.py | ||||
| 171 | +│ ├── 03_audit_schema.py | ||||
| 172 | +│ ├── 04_audit_market_calendar.py | ||||
| 173 | +│ ├── 05_audit_prices_and_volume.py | ||||
| 174 | +│ ├── 06_detect_corporate_actions.py | ||||
| 175 | +│ ├── 07_construct_security_master.py | ||||
| 176 | +│ ├── 08_build_clean_minute_panel.py | ||||
| 177 | +│ ├── 09_build_daily_metadata.py | ||||
| 178 | +│ ├── 10_construct_features.py | ||||
| 179 | +│ ├── 11_detect_shocks.py | ||||
| 180 | +│ ├── 12_estimate_networks.py | ||||
| 181 | +│ ├── 13_measure_propagation.py | ||||
| 182 | +│ ├── 14_run_baseline_regressions.py | ||||
| 183 | +│ ├── 15_run_event_studies.py | ||||
| 184 | +│ ├── 16_run_robustness.py | ||||
| 185 | +│ ├── 17_run_placebos.py | ||||
| 186 | +│ ├── 18_build_figures.py | ||||
| 187 | +│ ├── 19_build_tables.py | ||||
| 188 | +│ ├── 20_compile_paper.py | ||||
| 189 | +│ └── 21_validate_release.py | ||||
| 190 | +├── tests/ | ||||
| 191 | +│ ├── test_schema.py | ||||
| 192 | +│ ├── test_calendars.py | ||||
| 193 | +│ ├── test_cleaning.py | ||||
| 194 | +│ ├── test_features.py | ||||
| 195 | +│ ├── test_shocks.py | ||||
| 196 | +│ ├── test_networks.py | ||||
| 197 | +│ ├── test_econometrics.py | ||||
| 198 | +│ └── test_tables.py | ||||
| 199 | +├── outputs/ | ||||
| 200 | +│ ├── diagnostics/ | ||||
| 201 | +│ ├── estimates/ | ||||
| 202 | +│ ├── figures/ | ||||
| 203 | +│ ├── tables/ | ||||
| 204 | +│ ├── models/ | ||||
| 205 | +│ └── release/ | ||||
| 206 | +├── paper/ | ||||
| 207 | +│ ├── main.tex | ||||
| 208 | +│ ├── preamble.tex | ||||
| 209 | +│ ├── title_page.tex | ||||
| 210 | +│ ├── abstract.tex | ||||
| 211 | +│ ├── sections/ | ||||
| 212 | +│ │ ├── 01_introduction.tex | ||||
| 213 | +│ │ ├── 02_literature.tex | ||||
| 214 | +│ │ ├── 03_data.tex | ||||
| 215 | +│ │ ├── 04_measurement.tex | ||||
| 216 | +│ │ ├── 05_empirical_design.tex | ||||
| 217 | +│ │ ├── 06_results.tex | ||||
| 218 | +│ │ ├── 07_mechanisms.tex | ||||
| 219 | +│ │ ├── 08_robustness.tex | ||||
| 220 | +│ │ └── 09_conclusion.tex | ||||
| 221 | +│ ├── tables/ | ||||
| 222 | +│ ├── figures/ | ||||
| 223 | +│ ├── bibliography/ | ||||
| 224 | +│ │ └── references.bib | ||||
| 225 | +│ └── styles/ | ||||
| 226 | +├── appendix/ | ||||
| 227 | +│ ├── internet_appendix.tex | ||||
| 228 | +│ ├── sections/ | ||||
| 229 | +│ ├── tables/ | ||||
| 230 | +│ └── figures/ | ||||
| 231 | +└── docs/ | ||||
| 232 | + ├── DATA_DICTIONARY.md | ||||
| 233 | + ├── DATA_AUDIT.md | ||||
| 234 | + ├── EMPIRICAL_DESIGN.md | ||||
| 235 | + ├── LITERATURE_MAP.md | ||||
| 236 | + ├── REPRODUCIBILITY.md | ||||
| 237 | + ├── COMPUTE_LOG.md | ||||
| 238 | + ├── DECISION_LOG.md | ||||
| 239 | + └── LIMITATIONS.md | ||||
| 240 | +``` | ||||
| 241 | + | ||||
| 242 | +Use relative paths. No user-specific absolute path may appear in committed code. | ||||
| 243 | + | ||||
| 244 | +--- | ||||
| 245 | + | ||||
| 246 | +# 3. Execution protocol | ||||
| 247 | + | ||||
| 248 | +## 3.1 Work in stages | ||||
| 249 | + | ||||
| 250 | +Execute the project in the following order: | ||||
| 251 | + | ||||
| 252 | +### Stage A — Dataset discovery and minimal probe | ||||
| 253 | +Do not download the entire dataset immediately. First: | ||||
| 254 | + | ||||
| 255 | +1. inspect the Hugging Face repository metadata; | ||||
| 256 | +2. list all files, sizes, hashes if available, and last-modified information; | ||||
| 257 | +3. inspect the dataset card and revision history; | ||||
| 258 | +4. download only one early, one middle, and one recent monthly file; | ||||
| 259 | +5. infer the physical schema; | ||||
| 260 | +6. inspect timestamps, symbols, row counts, missingness, duplicates, price and volume units; | ||||
| 261 | +7. estimate total storage requirements after download, decompression, cleaning, features, and outputs; | ||||
| 262 | +8. write `docs/DATA_AUDIT.md` with preliminary findings; | ||||
| 263 | +9. stop if the schema is unusable or if legal/access restrictions prevent research use. | ||||
| 264 | + | ||||
| 265 | +### Stage B — Full download with manifest and resumability | ||||
| 266 | +Only after Stage A passes: | ||||
| 267 | + | ||||
| 268 | +1. download all target files; | ||||
| 269 | +2. use resumable transfers; | ||||
| 270 | +3. pin the exact dataset revision or commit hash; | ||||
| 271 | +4. save every file with checksum, byte size, row count, schema, and download timestamp; | ||||
| 272 | +5. never silently overwrite an existing file; | ||||
| 273 | +6. verify integrity before marking a file complete; | ||||
| 274 | +7. write a machine-readable manifest; | ||||
| 275 | +8. permit partial reruns and node-level parallelism. | ||||
| 276 | + | ||||
| 277 | +### Stage C — Raw-data audit | ||||
| 278 | +Before constructing returns: | ||||
| 279 | + | ||||
| 280 | +1. audit timestamp coverage; | ||||
| 281 | +2. map timestamps to the correct exchange timezone; | ||||
| 282 | +3. identify pre-market, regular, and after-hours observations; | ||||
| 283 | +4. inspect daylight-saving transitions; | ||||
| 284 | +5. compare observed minutes with the official U.S. exchange calendar; | ||||
| 285 | +6. identify half-days and exceptional closures; | ||||
| 286 | +7. detect duplicate symbol–timestamp observations; | ||||
| 287 | +8. detect non-monotonic timestamps; | ||||
| 288 | +9. detect impossible OHLC relationships; | ||||
| 289 | +10. inspect zeros, negative values, stale prices, and extreme volume; | ||||
| 290 | +11. identify possible split-related jumps; | ||||
| 291 | +12. inspect symbol reuse and ticker changes; | ||||
| 292 | +13. determine whether delisted securities are present; | ||||
| 293 | +14. quantify survivorship and look-ahead risks; | ||||
| 294 | +15. identify ETFs, ADRs, preferred shares, warrants, funds, and non-common-equity instruments where possible; | ||||
| 295 | +16. document uncertainty rather than guessing. | ||||
| 296 | + | ||||
| 297 | +### Stage D — Clean panel and metadata | ||||
| 298 | +Construct: | ||||
| 299 | + | ||||
| 300 | +- a regular-hours baseline panel; | ||||
| 301 | +- an extended-hours robustness panel; | ||||
| 302 | +- a broad universe; | ||||
| 303 | +- a conservative common-stock universe; | ||||
| 304 | +- a high-liquidity universe; | ||||
| 305 | +- a balanced-panel subsample only for diagnostics, never as the sole main sample. | ||||
| 306 | + | ||||
| 307 | +### Stage E — Descriptive evidence | ||||
| 308 | +Document: | ||||
| 309 | + | ||||
| 310 | +- sample coverage over time; | ||||
| 311 | +- number of securities; | ||||
| 312 | +- number of observations; | ||||
| 313 | +- missing minute patterns; | ||||
| 314 | +- intraday seasonality; | ||||
| 315 | +- cross-sectional distributions; | ||||
| 316 | +- volume concentration; | ||||
| 317 | +- volatility concentration; | ||||
| 318 | +- extreme-return frequency; | ||||
| 319 | +- changes over decades. | ||||
| 320 | + | ||||
| 321 | +### Stage F — Shock measurement and propagation | ||||
| 322 | +Implement the full empirical design described below. | ||||
| 323 | + | ||||
| 324 | +### Stage G — Tables, figures, and paper | ||||
| 325 | +All tables and figures must be generated from saved results. Never manually type numerical results into LaTeX. | ||||
| 326 | + | ||||
| 327 | +--- | ||||
| 328 | + | ||||
| 329 | +# 4. Data acquisition requirements | ||||
| 330 | + | ||||
| 331 | +## 4.1 Hugging Face access | ||||
| 332 | + | ||||
| 333 | +Use official Hugging Face tooling when practical: | ||||
| 334 | + | ||||
| 335 | +- `huggingface_hub` | ||||
| 336 | +- `hf_hub_download` | ||||
| 337 | +- repository file listing APIs | ||||
| 338 | +- revision pinning | ||||
| 339 | +- authenticated access only if required | ||||
| 340 | + | ||||
| 341 | +The downloader must support: | ||||
| 342 | + | ||||
| 343 | +- dry-run mode; | ||||
| 344 | +- file-range filters; | ||||
| 345 | +- year and month filters; | ||||
| 346 | +- retry with exponential backoff; | ||||
| 347 | +- resumability; | ||||
| 348 | +- maximum concurrent downloads; | ||||
| 349 | +- checksum verification; | ||||
| 350 | +- per-file logs; | ||||
| 351 | +- node-aware sharding; | ||||
| 352 | +- safe interruption; | ||||
| 353 | +- disk-space checks; | ||||
| 354 | +- idempotence. | ||||
| 355 | + | ||||
| 356 | +Create CLI commands such as: | ||||
| 357 | + | ||||
| 358 | +```bash | ||||
| 359 | +python -m intraday_fragility.cli probe-data | ||||
| 360 | +python -m intraday_fragility.cli download --start 1992-01 --end 2026-12 | ||||
| 361 | +python -m intraday_fragility.cli verify-download | ||||
| 362 | +python -m intraday_fragility.cli audit-raw | ||||
| 363 | +``` | ||||
| 364 | + | ||||
| 365 | +## 4.2 Manifest | ||||
| 366 | + | ||||
| 367 | +Create `data/manifests/raw_files.parquet` and `data/manifests/raw_files.csv` with at least: | ||||
| 368 | + | ||||
| 369 | +- dataset_id; | ||||
| 370 | +- dataset_revision; | ||||
| 371 | +- remote_path; | ||||
| 372 | +- local_path; | ||||
| 373 | +- year; | ||||
| 374 | +- month; | ||||
| 375 | +- expected_bytes; | ||||
| 376 | +- downloaded_bytes; | ||||
| 377 | +- sha256; | ||||
| 378 | +- status; | ||||
| 379 | +- download_started_at; | ||||
| 380 | +- download_completed_at; | ||||
| 381 | +- row_count; | ||||
| 382 | +- column_names; | ||||
| 383 | +- column_types; | ||||
| 384 | +- min_timestamp; | ||||
| 385 | +- max_timestamp; | ||||
| 386 | +- unique_symbol_count; | ||||
| 387 | +- duplicate_key_count; | ||||
| 388 | +- null_count_by_column; | ||||
| 389 | +- audit_version; | ||||
| 390 | +- code_commit. | ||||
| 391 | + | ||||
| 392 | +## 4.3 Never infer undocumented semantics | ||||
| 393 | + | ||||
| 394 | +For each field, determine and document: | ||||
| 395 | + | ||||
| 396 | +- exact name; | ||||
| 397 | +- data type; | ||||
| 398 | +- units; | ||||
| 399 | +- timezone; | ||||
| 400 | +- adjustment status; | ||||
| 401 | +- whether price is raw or split-adjusted; | ||||
| 402 | +- whether volume is raw or adjusted; | ||||
| 403 | +- whether timestamps denote bar open or bar close; | ||||
| 404 | +- whether bars with no trades are omitted or filled; | ||||
| 405 | +- whether symbols are point-in-time; | ||||
| 406 | +- whether source corrections are incorporated. | ||||
| 407 | + | ||||
| 408 | +If a property cannot be established, label it “unknown” and design robustness checks around that uncertainty. | ||||
| 409 | + | ||||
| 410 | +--- | ||||
| 411 | + | ||||
| 412 | +# 5. Data-quality audit | ||||
| 413 | + | ||||
| 414 | +## 5.1 Schema validation | ||||
| 415 | + | ||||
| 416 | +For every file and every batch, verify: | ||||
| 417 | + | ||||
| 418 | +\[ | ||||
| 419 | +\text{Low}_{i,t} \leq \min(\text{Open}_{i,t},\text{Close}_{i,t}) | ||||
| 420 | +\] | ||||
| 421 | + | ||||
| 422 | +and | ||||
| 423 | + | ||||
| 424 | +\[ | ||||
| 425 | +\text{High}_{i,t} \geq \max(\text{Open}_{i,t},\text{Close}_{i,t}) | ||||
| 426 | +\] | ||||
| 427 | + | ||||
| 428 | +as well as: | ||||
| 429 | + | ||||
| 430 | +\[ | ||||
| 431 | +\text{Low}_{i,t} \leq \text{High}_{i,t}. | ||||
| 432 | +\] | ||||
| 433 | + | ||||
| 434 | +Flag but do not automatically delete all violations. Report counts, rates, symbols, dates, and magnitudes. | ||||
| 435 | + | ||||
| 436 | +## 5.2 Timestamp and calendar checks | ||||
| 437 | + | ||||
| 438 | +Use a recognized exchange-calendar library and independently validate important dates. | ||||
| 439 | + | ||||
| 440 | +Baseline regular session: | ||||
| 441 | + | ||||
| 442 | +- 09:30 to 16:00 Eastern Time; | ||||
| 443 | +- respect historical calendar variation; | ||||
| 444 | +- handle early closes; | ||||
| 445 | +- handle daylight saving correctly; | ||||
| 446 | +- do not assume exactly 390 bars for every date. | ||||
| 447 | + | ||||
| 448 | +Determine whether the source timestamps are UTC, local exchange time, or another convention by empirical checks. | ||||
| 449 | + | ||||
| 450 | +## 5.3 Duplicate handling | ||||
| 451 | + | ||||
| 452 | +The natural key is initially assumed to be: | ||||
| 453 | + | ||||
| 454 | +```text | ||||
| 455 | +(symbol, timestamp) | ||||
| 456 | +``` | ||||
| 457 | + | ||||
| 458 | +But this assumption must be verified. | ||||
| 459 | + | ||||
| 460 | +For duplicate keys: | ||||
| 461 | + | ||||
| 462 | +1. check whether rows are identical; | ||||
| 463 | +2. inspect whether duplicates arise from multiple venues or source revisions; | ||||
| 464 | +3. preserve raw copies; | ||||
| 465 | +4. create deterministic resolution rules; | ||||
| 466 | +5. report sensitivity to alternative rules. | ||||
| 467 | + | ||||
| 468 | +## 5.4 Corporate actions | ||||
| 469 | + | ||||
| 470 | +OHLCV-based research is highly vulnerable to splits and ticker changes. | ||||
| 471 | + | ||||
| 472 | +Implement: | ||||
| 473 | + | ||||
| 474 | +- detection of discontinuities near rational split ratios; | ||||
| 475 | +- cross-checking against external corporate-action sources if legally and technically feasible; | ||||
| 476 | +- split flags; | ||||
| 477 | +- exclusion windows around suspected splits; | ||||
| 478 | +- robustness using close-to-close versus open-to-close returns; | ||||
| 479 | +- separate treatment of extreme jumps plausibly caused by corporate actions. | ||||
| 480 | + | ||||
| 481 | +Never winsorize away a possible split without logging it. | ||||
| 482 | + | ||||
| 483 | +## 5.5 Security identity | ||||
| 484 | + | ||||
| 485 | +A ticker is not a permanent security identifier. | ||||
| 486 | + | ||||
| 487 | +Attempt to construct or merge a point-in-time security master containing: | ||||
| 488 | + | ||||
| 489 | +- ticker; | ||||
| 490 | +- permanent identifier if available; | ||||
| 491 | +- issuer name; | ||||
| 492 | +- security type; | ||||
| 493 | +- exchange; | ||||
| 494 | +- listing and delisting dates; | ||||
| 495 | +- sector and industry; | ||||
| 496 | +- ETF indicator; | ||||
| 497 | +- ADR indicator; | ||||
| 498 | +- common-stock indicator; | ||||
| 499 | +- share class. | ||||
| 500 | + | ||||
| 501 | +If permanent identifiers cannot be recovered for the full period: | ||||
| 502 | + | ||||
| 503 | +- explicitly state this limitation; | ||||
| 504 | +- avoid interpreting long ticker histories as one unchanged security; | ||||
| 505 | +- create ticker-spell intervals; | ||||
| 506 | +- run conservative analyses within continuous ticker episodes. | ||||
| 507 | + | ||||
| 508 | +## 5.6 Survivorship bias | ||||
| 509 | + | ||||
| 510 | +Determine whether the data include delisted securities and whether historical files preserve the contemporaneous universe. | ||||
| 511 | + | ||||
| 512 | +Produce: | ||||
| 513 | + | ||||
| 514 | +- yearly entry counts; | ||||
| 515 | +- yearly exit counts; | ||||
| 516 | +- symbol survival curves; | ||||
| 517 | +- sample counts by vintage; | ||||
| 518 | +- comparisons of balanced and unbalanced panels; | ||||
| 519 | +- a formal discussion of possible survivorship bias. | ||||
| 520 | + | ||||
| 521 | +## 5.7 Missingness | ||||
| 522 | + | ||||
| 523 | +Measure missingness at: | ||||
| 524 | + | ||||
| 525 | +- file level; | ||||
| 526 | +- day level; | ||||
| 527 | +- symbol-day level; | ||||
| 528 | +- minute-of-day level; | ||||
| 529 | +- decade level; | ||||
| 530 | +- market-state level. | ||||
| 531 | + | ||||
| 532 | +Do not forward-fill prices in the main analysis unless the precise estimand requires a regular grid. If a regular grid is needed: | ||||
| 533 | + | ||||
| 534 | +- distinguish “no recorded bar” from “zero return”; | ||||
| 535 | +- retain a missing-trade indicator; | ||||
| 536 | +- report results without imputation; | ||||
| 537 | +- use previous-tick interpolation only in explicitly labeled robustness analyses. | ||||
| 538 | + | ||||
| 539 | +--- | ||||
| 540 | + | ||||
| 541 | +# 6. Sample construction | ||||
| 542 | + | ||||
| 543 | +Create transparent sample filters in `config/sample_filters.yaml`. | ||||
| 544 | + | ||||
| 545 | +## 6.1 Baseline universe | ||||
| 546 | + | ||||
| 547 | +The baseline should target U.S.-listed common equities during regular trading hours, subject to defensible filters such as: | ||||
| 548 | + | ||||
| 549 | +- valid OHLC; | ||||
| 550 | +- positive price; | ||||
| 551 | +- positive or nonnegative volume as appropriate; | ||||
| 552 | +- minimum number of valid bars per day; | ||||
| 553 | +- minimum trading history; | ||||
| 554 | +- exclusion of obvious corporate-action contamination; | ||||
| 555 | +- removal of duplicate records; | ||||
| 556 | +- no use of future information in inclusion rules. | ||||
| 557 | + | ||||
| 558 | +## 6.2 Alternative universes | ||||
| 559 | + | ||||
| 560 | +Construct at least: | ||||
| 561 | + | ||||
| 562 | +1. all available instruments; | ||||
| 563 | +2. common stocks only; | ||||
| 564 | +3. stocks excluding ETFs and ADRs; | ||||
| 565 | +4. liquid stocks based on lagged information; | ||||
| 566 | +5. price above a lagged threshold; | ||||
| 567 | +6. top 500, 1,000, and 3,000 securities by lagged dollar volume; | ||||
| 568 | +7. continuous-history subsample; | ||||
| 569 | +8. pre-2001, 2001–2009, 2010–2019, and 2020 onward; | ||||
| 570 | +9. regular-hours only; | ||||
| 571 | +10. extended-hours included. | ||||
| 572 | + | ||||
| 573 | +Any liquidity-based inclusion criterion must use lagged data to avoid look-ahead bias. | ||||
| 574 | + | ||||
| 575 | +--- | ||||
| 576 | + | ||||
| 577 | +# 7. Variable construction | ||||
| 578 | + | ||||
| 579 | +All features must be defined in `docs/DATA_DICTIONARY.md` with formula, timing, units, and availability. | ||||
| 580 | + | ||||
| 581 | +## 7.1 Returns | ||||
| 582 | + | ||||
| 583 | +Construct: | ||||
| 584 | + | ||||
| 585 | +\[ | ||||
| 586 | +r_{i,t} = \log(P_{i,t})-\log(P_{i,t-1}). | ||||
| 587 | +\] | ||||
| 588 | + | ||||
| 589 | +Use alternative prices: | ||||
| 590 | + | ||||
| 591 | +- close-to-close minute return; | ||||
| 592 | +- open-to-close bar return; | ||||
| 593 | +- midpoint proxy \((H+L)/2\) only as robustness; | ||||
| 594 | +- previous valid close return; | ||||
| 595 | +- overnight return separately. | ||||
| 596 | + | ||||
| 597 | +Never bridge overnight and intraday returns without an explicit definition. | ||||
| 598 | + | ||||
| 599 | +## 7.2 Realized volatility | ||||
| 600 | + | ||||
| 601 | +At stock-day level: | ||||
| 602 | + | ||||
| 603 | +\[ | ||||
| 604 | +RV_{i,d} = \sum_{t \in d} r_{i,t}^{2}. | ||||
| 605 | +\] | ||||
| 606 | + | ||||
| 607 | +Construct: | ||||
| 608 | + | ||||
| 609 | +- 5-minute RV; | ||||
| 610 | +- 15-minute RV; | ||||
| 611 | +- 30-minute RV; | ||||
| 612 | +- daily RV; | ||||
| 613 | +- upside and downside semivariance; | ||||
| 614 | +- bipower variation if data quality permits; | ||||
| 615 | +- jump proxies; | ||||
| 616 | +- realized quarticity. | ||||
| 617 | + | ||||
| 618 | +## 7.3 Range-based measures | ||||
| 619 | + | ||||
| 620 | +Examples: | ||||
| 621 | + | ||||
| 622 | +\[ | ||||
| 623 | +Range_{i,t}=\log(H_{i,t})-\log(L_{i,t}) | ||||
| 624 | +\] | ||||
| 625 | + | ||||
| 626 | +and established range-based volatility estimators when their assumptions are defensible. | ||||
| 627 | + | ||||
| 628 | +## 7.4 Trading activity | ||||
| 629 | + | ||||
| 630 | +Construct: | ||||
| 631 | + | ||||
| 632 | +- raw volume; | ||||
| 633 | +- log volume; | ||||
| 634 | +- dollar volume; | ||||
| 635 | +- turnover if shares outstanding become available; | ||||
| 636 | +- volume relative to the same minute of the day; | ||||
| 637 | +- volume z-score based only on lagged observations; | ||||
| 638 | +- fraction of daily volume occurring in each interval; | ||||
| 639 | +- market-wide and sector-wide volume concentration. | ||||
| 640 | + | ||||
| 641 | +## 7.5 OHLCV-based illiquidity and price-impact proxies | ||||
| 642 | + | ||||
| 643 | +Possible proxies include: | ||||
| 644 | + | ||||
| 645 | +\[ | ||||
| 646 | +ILLIQ_{i,t} = \frac{|r_{i,t}|}{DollarVolume_{i,t}+\epsilon}. | ||||
| 647 | +\] | ||||
| 648 | + | ||||
| 649 | +Also consider: | ||||
| 650 | + | ||||
| 651 | +- high-low range divided by dollar volume; | ||||
| 652 | +- absolute residual return per unit of volume; | ||||
| 653 | +- zero-return frequency; | ||||
| 654 | +- stale-price duration; | ||||
| 655 | +- Roll-type proxies only if valid at the available frequency; | ||||
| 656 | +- Corwin–Schultz estimates only at a frequency consistent with the estimator. | ||||
| 657 | + | ||||
| 658 | +Use multiple proxies because no single OHLCV measure identifies true liquidity. | ||||
| 659 | + | ||||
| 660 | +## 7.6 Intraday seasonality | ||||
| 661 | + | ||||
| 662 | +For each variable, estimate minute-of-day seasonality using only historical information or a clearly defined full-sample descriptive normalization. | ||||
| 663 | + | ||||
| 664 | +Main predictive and causal specifications must use lagged or training-period seasonality estimates. | ||||
| 665 | + | ||||
| 666 | +Construct standardized variables: | ||||
| 667 | + | ||||
| 668 | +\[ | ||||
| 669 | +z_{i,t}^{x} | ||||
| 670 | += | ||||
| 671 | +\frac{x_{i,t}-\widehat{\mu}_{i,\tau(t)}}{\widehat{\sigma}_{i,\tau(t)}}, | ||||
| 672 | +\] | ||||
| 673 | + | ||||
| 674 | +where \(\tau(t)\) is minute of day. | ||||
| 675 | + | ||||
| 676 | +Use robust alternatives based on the median and MAD. | ||||
| 677 | + | ||||
| 678 | +--- | ||||
| 679 | + | ||||
| 680 | +# 8. Defining idiosyncratic intraday shocks | ||||
| 681 | + | ||||
| 682 | +A raw extreme return is not necessarily idiosyncratic. Construct several shock definitions. | ||||
| 683 | + | ||||
| 684 | +## 8.1 Residual return model | ||||
| 685 | + | ||||
| 686 | +Estimate rolling or recursively updated models such as: | ||||
| 687 | + | ||||
| 688 | +\[ | ||||
| 689 | +r_{i,t} | ||||
| 690 | += | ||||
| 691 | +\alpha_{i,\tau} | ||||
| 692 | ++\beta_{i,m,t}r_{m,t} | ||||
| 693 | ++\beta_{i,s,t}r_{s(i),t} | ||||
| 694 | ++\boldsymbol{\gamma}_{i,t}'F_t | ||||
| 695 | ++\varepsilon_{i,t}, | ||||
| 696 | +\] | ||||
| 697 | + | ||||
| 698 | +where: | ||||
| 699 | + | ||||
| 700 | +- \(r_{m,t}\) is a broad market return; | ||||
| 701 | +- \(r_{s(i),t}\) is the sector return; | ||||
| 702 | +- \(F_t\) may contain principal components or other common factors; | ||||
| 703 | +- \(\alpha_{i,\tau}\) absorbs intraday seasonality. | ||||
| 704 | + | ||||
| 705 | +Prevent mechanical contamination by excluding stock \(i\) from market and sector aggregates when feasible. | ||||
| 706 | + | ||||
| 707 | +## 8.2 Shock threshold | ||||
| 708 | + | ||||
| 709 | +Define a baseline shock as: | ||||
| 710 | + | ||||
| 711 | +\[ | ||||
| 712 | +Shock_{i,t}=1\left( | ||||
| 713 | +|\varepsilon_{i,t}| > | ||||
| 714 | +q_{i,\tau,t}(p) | ||||
| 715 | +\right), | ||||
| 716 | +\] | ||||
| 717 | + | ||||
| 718 | +where \(q_{i,\tau,t}(p)\) is a lagged conditional extreme quantile. | ||||
| 719 | + | ||||
| 720 | +Use thresholds such as: | ||||
| 721 | + | ||||
| 722 | +- 99th percentile; | ||||
| 723 | +- 99.5th percentile; | ||||
| 724 | +- 99.9th percentile; | ||||
| 725 | +- 4, 5, and 6 robust standard deviations; | ||||
| 726 | +- extreme-value-theory thresholds; | ||||
| 727 | +- jump-test thresholds. | ||||
| 728 | + | ||||
| 729 | +Separate: | ||||
| 730 | + | ||||
| 731 | +- positive shocks; | ||||
| 732 | +- negative shocks; | ||||
| 733 | +- return shocks; | ||||
| 734 | +- volatility shocks; | ||||
| 735 | +- volume shocks; | ||||
| 736 | +- combined return-volume shocks; | ||||
| 737 | +- range shocks; | ||||
| 738 | +- illiquidity-proxy shocks. | ||||
| 739 | + | ||||
| 740 | +## 8.3 Shock isolation | ||||
| 741 | + | ||||
| 742 | +To reduce common-news contamination, require one or more of: | ||||
| 743 | + | ||||
| 744 | +- low contemporaneous market return; | ||||
| 745 | +- low contemporaneous sector return; | ||||
| 746 | +- large idiosyncratic residual; | ||||
| 747 | +- leave-one-out factor construction; | ||||
| 748 | +- no simultaneous extreme shock in a large fraction of the market; | ||||
| 749 | +- exclusion of scheduled macro announcement windows for the idiosyncratic baseline; | ||||
| 750 | +- separate common-shock sample. | ||||
| 751 | + | ||||
| 752 | +Do not define isolation so strictly that only trivial events remain. Report the trade-off. | ||||
| 753 | + | ||||
| 754 | +--- | ||||
| 755 | + | ||||
| 756 | +# 9. Measuring propagation | ||||
| 757 | + | ||||
| 758 | +## 9.1 Outcome horizons | ||||
| 759 | + | ||||
| 760 | +Use horizons: | ||||
| 761 | + | ||||
| 762 | +\[ | ||||
| 763 | +h \in \{1,2,5,10,15,30,60,120\}\text{ minutes}. | ||||
| 764 | +\] | ||||
| 765 | + | ||||
| 766 | +Respect session boundaries. Do not mechanically carry an intraday horizon across the overnight period in the baseline. | ||||
| 767 | + | ||||
| 768 | +## 9.2 Breadth | ||||
| 769 | + | ||||
| 770 | +Define market-wide propagation breadth: | ||||
| 771 | + | ||||
| 772 | +\[ | ||||
| 773 | +Breadth_{i,t}(h) | ||||
| 774 | += | ||||
| 775 | +\frac{1}{N_{t,h}-1} | ||||
| 776 | +\sum_{j\neq i} | ||||
| 777 | +1\left(|AR_{j,t+h}|>q_{j,\tau,t}\right). | ||||
| 778 | +\] | ||||
| 779 | + | ||||
| 780 | +Also define: | ||||
| 781 | + | ||||
| 782 | +- cumulative breadth through \(h\); | ||||
| 783 | +- sector breadth; | ||||
| 784 | +- connected-neighbor breadth; | ||||
| 785 | +- non-sector breadth; | ||||
| 786 | +- breadth weighted by lagged dollar volume; | ||||
| 787 | +- breadth weighted by network proximity. | ||||
| 788 | + | ||||
| 789 | +## 9.3 Speed | ||||
| 790 | + | ||||
| 791 | +Define: | ||||
| 792 | + | ||||
| 793 | +- minutes until 1%, 5%, 10%, or 25% of eligible securities react; | ||||
| 794 | +- time to peak breadth; | ||||
| 795 | +- half-life of the response; | ||||
| 796 | +- propagation velocity over network distance; | ||||
| 797 | +- hazard of first response. | ||||
| 798 | + | ||||
| 799 | +If a threshold is never reached, treat the observation as right-censored rather than assigning an arbitrary large value. | ||||
| 800 | + | ||||
| 801 | +## 9.4 Intensity | ||||
| 802 | + | ||||
| 803 | +Define: | ||||
| 804 | + | ||||
| 805 | +\[ | ||||
| 806 | +Intensity_{i,t}(h) | ||||
| 807 | += | ||||
| 808 | +\frac{1}{N-1} | ||||
| 809 | +\sum_{j\neq i}|AR_{j,t+h}|. | ||||
| 810 | +\] | ||||
| 811 | + | ||||
| 812 | +Construct signed and unsigned versions. | ||||
| 813 | + | ||||
| 814 | +## 9.5 Amplification | ||||
| 815 | + | ||||
| 816 | +Define the Intraday Shock Amplification Ratio: | ||||
| 817 | + | ||||
| 818 | +\[ | ||||
| 819 | +ISAR_{i,t}(h) | ||||
| 820 | += | ||||
| 821 | +\frac{ | ||||
| 822 | +\sum_{j\neq i}w_{ij,t}|AR_{j,t+h}| | ||||
| 823 | +}{ | ||||
| 824 | +|\varepsilon_{i,t}|+\epsilon | ||||
| 825 | +}. | ||||
| 826 | +\] | ||||
| 827 | + | ||||
| 828 | +Explore alternative normalizations and show that results are not artifacts of a small denominator. | ||||
| 829 | + | ||||
| 830 | +## 9.6 Persistence | ||||
| 831 | + | ||||
| 832 | +Measure: | ||||
| 833 | + | ||||
| 834 | +- cumulative response; | ||||
| 835 | +- response half-life; | ||||
| 836 | +- reversal after the initial response; | ||||
| 837 | +- permanent versus transitory components; | ||||
| 838 | +- integrated response over 5, 15, 30, 60, and 120 minutes. | ||||
| 839 | + | ||||
| 840 | +## 9.7 Asymmetry | ||||
| 841 | + | ||||
| 842 | +Estimate separate responses to: | ||||
| 843 | + | ||||
| 844 | +- positive versus negative shocks; | ||||
| 845 | +- high versus low market volatility; | ||||
| 846 | +- opening, midday, and closing periods; | ||||
| 847 | +- high versus low aggregate correlation; | ||||
| 848 | +- high versus low market concentration; | ||||
| 849 | +- liquid versus illiquid source securities; | ||||
| 850 | +- large versus small shock magnitude. | ||||
| 851 | + | ||||
| 852 | +--- | ||||
| 853 | + | ||||
| 854 | +# 10. Dynamic network construction | ||||
| 855 | + | ||||
| 856 | +The network must be estimated using information available before the shock. | ||||
| 857 | + | ||||
| 858 | +## 10.1 Candidate networks | ||||
| 859 | + | ||||
| 860 | +Estimate several networks: | ||||
| 861 | + | ||||
| 862 | +1. sector membership; | ||||
| 863 | +2. rolling return correlation; | ||||
| 864 | +3. partial correlation; | ||||
| 865 | +4. lead-lag predictive network; | ||||
| 866 | +5. volume-shock correlation; | ||||
| 867 | +6. volatility-spillover network; | ||||
| 868 | +7. sparse VAR; | ||||
| 869 | +8. graphical LASSO; | ||||
| 870 | +9. low-rank plus sparse network; | ||||
| 871 | +10. dynamic factor residual network; | ||||
| 872 | +11. Granger-style predictive network; | ||||
| 873 | +12. learned graph representation, used as an extension rather than the sole method. | ||||
| 874 | + | ||||
| 875 | +## 10.2 Timing discipline | ||||
| 876 | + | ||||
| 877 | +For a shock at time \(t\), network weights \(W_{ij,t}\) must be estimated only from data dated strictly before \(t\). | ||||
| 878 | + | ||||
| 879 | +Use: | ||||
| 880 | + | ||||
| 881 | +- rolling windows; | ||||
| 882 | +- expanding windows; | ||||
| 883 | +- annual network freezes; | ||||
| 884 | +- monthly network freezes; | ||||
| 885 | +- cross-fitted network estimation. | ||||
| 886 | + | ||||
| 887 | +## 10.3 Centrality and roles | ||||
| 888 | + | ||||
| 889 | +Compute lagged: | ||||
| 890 | + | ||||
| 891 | +- out-strength; | ||||
| 892 | +- in-strength; | ||||
| 893 | +- eigenvector centrality; | ||||
| 894 | +- PageRank; | ||||
| 895 | +- betweenness; | ||||
| 896 | +- community bridge score; | ||||
| 897 | +- k-core; | ||||
| 898 | +- participation coefficient; | ||||
| 899 | +- transmitter and receiver scores. | ||||
| 900 | + | ||||
| 901 | +Define economic roles: | ||||
| 902 | + | ||||
| 903 | +- transmitter; | ||||
| 904 | +- receiver; | ||||
| 905 | +- amplifier; | ||||
| 906 | +- absorber; | ||||
| 907 | +- bridge; | ||||
| 908 | +- isolated security. | ||||
| 909 | + | ||||
| 910 | +Do not infer economic importance from one centrality measure alone. | ||||
| 911 | + | ||||
| 912 | +--- | ||||
| 913 | + | ||||
| 914 | +# 11. Baseline econometric designs | ||||
| 915 | + | ||||
| 916 | +## 11.1 Local projections | ||||
| 917 | + | ||||
| 918 | +Estimate horizon-specific responses: | ||||
| 919 | + | ||||
| 920 | +\[ | ||||
| 921 | +Y_{j,t+h} | ||||
| 922 | += | ||||
| 923 | +\alpha_{j} | ||||
| 924 | ++\delta_{\tau(t)} | ||||
| 925 | ++\lambda_{d} | ||||
| 926 | ++\beta_h Shock_{i,t} | ||||
| 927 | ++\theta_h Shock_{i,t}W_{ij,t^-} | ||||
| 928 | ++\Gamma_h'X_{i,j,t^-} | ||||
| 929 | ++u_{i,j,t+h}. | ||||
| 930 | +\] | ||||
| 931 | + | ||||
| 932 | +Possible fixed effects: | ||||
| 933 | + | ||||
| 934 | +- receiver security; | ||||
| 935 | +- source security; | ||||
| 936 | +- date; | ||||
| 937 | +- minute of day; | ||||
| 938 | +- source-by-year; | ||||
| 939 | +- receiver-by-year; | ||||
| 940 | +- sector-by-date; | ||||
| 941 | +- market-state bins. | ||||
| 942 | + | ||||
| 943 | +Do not include fixed effects that absorb the variable of interest without recognizing it. | ||||
| 944 | + | ||||
| 945 | +## 11.2 Cascade-level regressions | ||||
| 946 | + | ||||
| 947 | +At the source-shock level: | ||||
| 948 | + | ||||
| 949 | +\[ | ||||
| 950 | +Cascade_{i,t}(h) | ||||
| 951 | += | ||||
| 952 | +\alpha | ||||
| 953 | ++\beta_1 Magnitude_{i,t} | ||||
| 954 | ++\beta_2 Negative_{i,t} | ||||
| 955 | ++\beta_3 Centrality_{i,t^-} | ||||
| 956 | ++\beta_4 State_{t^-} | ||||
| 957 | ++\beta_5 Magnitude_{i,t}\times State_{t^-} | ||||
| 958 | ++\mu_i+\lambda_d+\delta_{\tau} | ||||
| 959 | ++\varepsilon_{i,t,h}. | ||||
| 960 | +\] | ||||
| 961 | + | ||||
| 962 | +## 11.3 Long-run evolution | ||||
| 963 | + | ||||
| 964 | +Estimate flexible time variation: | ||||
| 965 | + | ||||
| 966 | +- year fixed effects interacted with shock magnitude; | ||||
| 967 | +- rolling coefficients; | ||||
| 968 | +- decade bins; | ||||
| 969 | +- splines; | ||||
| 970 | +- structural-break tests; | ||||
| 971 | +- distributional regressions; | ||||
| 972 | +- quantile regressions. | ||||
| 973 | + | ||||
| 974 | +Do not impose a linear “algorithmic trading trend” as the only model. | ||||
| 975 | + | ||||
| 976 | +## 11.4 Nonlinearity | ||||
| 977 | + | ||||
| 978 | +Test whether propagation changes sharply beyond a threshold: | ||||
| 979 | + | ||||
| 980 | +- binscatter with confidence intervals; | ||||
| 981 | +- local polynomial; | ||||
| 982 | +- splines; | ||||
| 983 | +- threshold regression; | ||||
| 984 | +- generalized random forest for heterogeneity; | ||||
| 985 | +- quantile treatment effects where appropriate; | ||||
| 986 | +- monotonicity checks. | ||||
| 987 | + | ||||
| 988 | +The primary nonlinear result must also be represented with a transparent non-ML specification. | ||||
| 989 | + | ||||
| 990 | +## 11.5 Inference | ||||
| 991 | + | ||||
| 992 | +High-frequency observations are strongly dependent. | ||||
| 993 | + | ||||
| 994 | +Consider: | ||||
| 995 | + | ||||
| 996 | +- two-way clustering by source security and date; | ||||
| 997 | +- clustering by date and minute block; | ||||
| 998 | +- source-shock-level aggregation; | ||||
| 999 | +- block bootstrap by trading day; | ||||
| 1000 | +- stationary bootstrap; | ||||
| 1001 | +- randomization inference for event studies; | ||||
| 1002 | +- Driscoll–Kraay only if its assumptions fit; | ||||
| 1003 | +- multiple-hypothesis correction for families of outcomes. | ||||
| 1004 | + | ||||
| 1005 | +Report why each inference method is appropriate. | ||||
| 1006 | + | ||||
| 1007 | +--- | ||||
| 1008 | + | ||||
| 1009 | +# 12. Identification and common-information problem | ||||
| 1010 | + | ||||
| 1011 | +The central threat is that many securities react to the same information rather than to each other. | ||||
| 1012 | + | ||||
| 1013 | +Address this directly. | ||||
| 1014 | + | ||||
| 1015 | +## 12.1 Scheduled macro announcements | ||||
| 1016 | + | ||||
| 1017 | +Construct an event database for major U.S. announcements where reliable historical timestamps and surprise measures are available: | ||||
| 1018 | + | ||||
| 1019 | +- FOMC decisions and statements; | ||||
| 1020 | +- CPI; | ||||
| 1021 | +- employment report; | ||||
| 1022 | +- GDP; | ||||
| 1023 | +- retail sales; | ||||
| 1024 | +- PPI; | ||||
| 1025 | +- ISM; | ||||
| 1026 | +- other major scheduled releases. | ||||
| 1027 | + | ||||
| 1028 | +Use these events to: | ||||
| 1029 | + | ||||
| 1030 | +1. characterize common shocks; | ||||
| 1031 | +2. estimate separate propagation patterns; | ||||
| 1032 | +3. exclude macro windows from the idiosyncratic baseline; | ||||
| 1033 | +4. compare common-news and firm-originating shock dynamics. | ||||
| 1034 | + | ||||
| 1035 | +## 12.2 Firm-specific news | ||||
| 1036 | + | ||||
| 1037 | +If reliable timestamped news or earnings-announcement data can be added: | ||||
| 1038 | + | ||||
| 1039 | +- identify plausibly firm-specific shocks; | ||||
| 1040 | +- distinguish pre-market, intraday, and after-hours announcements; | ||||
| 1041 | +- use narrow event windows; | ||||
| 1042 | +- avoid post-treatment controls; | ||||
| 1043 | +- test whether economically linked firms respond more strongly. | ||||
| 1044 | + | ||||
| 1045 | +Do not use scraped or low-quality event timestamps without validation. | ||||
| 1046 | + | ||||
| 1047 | +## 12.3 Placebo timing | ||||
| 1048 | + | ||||
| 1049 | +For each real shock: | ||||
| 1050 | + | ||||
| 1051 | +- assign same-stock placebo times on comparable non-event days; | ||||
| 1052 | +- preserve minute-of-day and volatility state; | ||||
| 1053 | +- repeat the propagation analysis; | ||||
| 1054 | +- compare real and placebo distributions. | ||||
| 1055 | + | ||||
| 1056 | +## 12.4 Permuted networks | ||||
| 1057 | + | ||||
| 1058 | +Randomly permute network links while preserving: | ||||
| 1059 | + | ||||
| 1060 | +- degree distribution; | ||||
| 1061 | +- sector composition; | ||||
| 1062 | +- size bins; | ||||
| 1063 | +- liquidity bins. | ||||
| 1064 | + | ||||
| 1065 | +True networks should outperform matched placebo networks if network propagation is economically meaningful. | ||||
| 1066 | + | ||||
| 1067 | +## 12.5 Negative controls | ||||
| 1068 | + | ||||
| 1069 | +Potential negative controls: | ||||
| 1070 | + | ||||
| 1071 | +- future network weights; | ||||
| 1072 | +- distant unrelated securities; | ||||
| 1073 | +- pre-shock outcomes; | ||||
| 1074 | +- randomized source identity; | ||||
| 1075 | +- non-overlapping time windows. | ||||
| 1076 | + | ||||
| 1077 | +Future information may be used only as a falsification test, never in the baseline estimator. | ||||
| 1078 | + | ||||
| 1079 | +--- | ||||
| 1080 | + | ||||
| 1081 | +# 13. Market-structure evolution | ||||
| 1082 | + | ||||
| 1083 | +The paper may discuss algorithmic and electronic trading, but OHLCV data do not directly measure algorithmic trading intensity. | ||||
| 1084 | + | ||||
| 1085 | +Therefore: | ||||
| 1086 | + | ||||
| 1087 | +- do not claim a causal effect of algorithmic trading from a time trend alone; | ||||
| 1088 | +- identify documented market-structure milestones from authoritative sources; | ||||
| 1089 | +- treat breakpoint evidence cautiously; | ||||
| 1090 | +- consider alternative explanations: | ||||
| 1091 | + - decimalization; | ||||
| 1092 | + - ETF growth; | ||||
| 1093 | + - passive investment; | ||||
| 1094 | + - market fragmentation; | ||||
| 1095 | + - faster information diffusion; | ||||
| 1096 | + - changes in listing composition; | ||||
| 1097 | + - changes in data coverage; | ||||
| 1098 | + - crisis composition; | ||||
| 1099 | + - regulation; | ||||
| 1100 | + - macro volatility; | ||||
| 1101 | + - changing sector weights. | ||||
| 1102 | + | ||||
| 1103 | +Potential periodization must be pre-specified and justified. Results should also be shown using flexible year effects rather than only hand-picked eras. | ||||
| 1104 | + | ||||
| 1105 | +--- | ||||
| 1106 | + | ||||
| 1107 | +# 14. Machine learning and foundation-model extension | ||||
| 1108 | + | ||||
| 1109 | +A machine-learning component may be included, but it must not obscure identification. | ||||
| 1110 | + | ||||
| 1111 | +## 14.1 Prediction task | ||||
| 1112 | + | ||||
| 1113 | +Predict at shock time \(t\): | ||||
| 1114 | + | ||||
| 1115 | +- future breadth; | ||||
| 1116 | +- future intensity; | ||||
| 1117 | +- time to cascade; | ||||
| 1118 | +- sector-to-market transition; | ||||
| 1119 | +- probability of a tail cascade. | ||||
| 1120 | + | ||||
| 1121 | +## 14.2 Data splitting | ||||
| 1122 | + | ||||
| 1123 | +Use strict temporal splits: | ||||
| 1124 | + | ||||
| 1125 | +- training period; | ||||
| 1126 | +- validation period; | ||||
| 1127 | +- final untouched test period; | ||||
| 1128 | +- optional rolling-origin evaluation. | ||||
| 1129 | + | ||||
| 1130 | +Never randomly split minute observations across train and test. | ||||
| 1131 | + | ||||
| 1132 | +## 14.3 Baselines | ||||
| 1133 | + | ||||
| 1134 | +Compare with: | ||||
| 1135 | + | ||||
| 1136 | +- unconditional historical mean; | ||||
| 1137 | +- linear and logistic regressions; | ||||
| 1138 | +- penalized regression; | ||||
| 1139 | +- random forest; | ||||
| 1140 | +- gradient boosting; | ||||
| 1141 | +- HAR-style models; | ||||
| 1142 | +- VAR and sparse VAR; | ||||
| 1143 | +- Hawkes-inspired specifications where feasible; | ||||
| 1144 | +- LSTM; | ||||
| 1145 | +- temporal convolution; | ||||
| 1146 | +- transformer or state-space model; | ||||
| 1147 | +- graph neural network; | ||||
| 1148 | +- model without network information; | ||||
| 1149 | +- model without market-state information. | ||||
| 1150 | + | ||||
| 1151 | +## 14.4 Evaluation | ||||
| 1152 | + | ||||
| 1153 | +Report: | ||||
| 1154 | + | ||||
| 1155 | +- out-of-sample \(R^2\); | ||||
| 1156 | +- log loss; | ||||
| 1157 | +- Brier score; | ||||
| 1158 | +- AUROC; | ||||
| 1159 | +- precision-recall AUC; | ||||
| 1160 | +- calibration; | ||||
| 1161 | +- tail recall; | ||||
| 1162 | +- economic ranking performance; | ||||
| 1163 | +- stability across years and regimes. | ||||
| 1164 | + | ||||
| 1165 | +No trading strategy should be the main evidence. Any economic-value exercise must incorporate conservative transaction-cost assumptions and be clearly secondary. | ||||
| 1166 | + | ||||
| 1167 | +## 14.5 Interpretability | ||||
| 1168 | + | ||||
| 1169 | +Use: | ||||
| 1170 | + | ||||
| 1171 | +- partial dependence; | ||||
| 1172 | +- accumulated local effects; | ||||
| 1173 | +- SHAP with dependence-aware interpretation; | ||||
| 1174 | +- feature ablation; | ||||
| 1175 | +- network ablation; | ||||
| 1176 | +- temporal ablation; | ||||
| 1177 | +- regime-specific performance; | ||||
| 1178 | +- calibration plots. | ||||
| 1179 | + | ||||
| 1180 | +Do not treat model attention weights as causal explanations. | ||||
| 1181 | + | ||||
| 1182 | +--- | ||||
| 1183 | + | ||||
| 1184 | +# 15. Required robustness analyses | ||||
| 1185 | + | ||||
| 1186 | +At minimum, run: | ||||
| 1187 | + | ||||
| 1188 | +1. alternative return definitions; | ||||
| 1189 | +2. alternative shock thresholds; | ||||
| 1190 | +3. alternative factor residualizations; | ||||
| 1191 | +4. alternative market and sector benchmarks; | ||||
| 1192 | +5. alternative network definitions; | ||||
| 1193 | +6. alternative network estimation windows; | ||||
| 1194 | +7. alternative security universes; | ||||
| 1195 | +8. exclusion of ETFs; | ||||
| 1196 | +9. exclusion of ADRs; | ||||
| 1197 | +10. exclusion of penny stocks; | ||||
| 1198 | +11. exclusion of suspected split windows; | ||||
| 1199 | +12. regular-hours only; | ||||
| 1200 | +13. alternative minute aggregation: 1, 5, 10, and 15 minutes; | ||||
| 1201 | +14. volume-weighted and equal-weighted outcomes; | ||||
| 1202 | +15. opening and closing exclusions; | ||||
| 1203 | +16. crisis versus non-crisis samples; | ||||
| 1204 | +17. macro-announcement exclusions; | ||||
| 1205 | +18. day-block bootstrap; | ||||
| 1206 | +19. matched placebo shocks; | ||||
| 1207 | +20. permuted networks; | ||||
| 1208 | +21. pre-trend and pre-response tests; | ||||
| 1209 | +22. source-stock fixed effects; | ||||
| 1210 | +23. receiver-stock fixed effects; | ||||
| 1211 | +24. date fixed effects; | ||||
| 1212 | +25. sector-by-date fixed effects where computationally feasible; | ||||
| 1213 | +26. balanced versus unbalanced samples; | ||||
| 1214 | +27. winsorized versus non-winsorized outcomes; | ||||
| 1215 | +28. median-based robust standardization; | ||||
| 1216 | +29. alternative right-censoring treatment for propagation time; | ||||
| 1217 | +30. multiple-testing adjustments. | ||||
| 1218 | + | ||||
| 1219 | +Robustness must test the economic interpretation, not merely produce many similar regressions. | ||||
| 1220 | + | ||||
| 1221 | +--- | ||||
| 1222 | + | ||||
| 1223 | +# 16. Falsification tests | ||||
| 1224 | + | ||||
| 1225 | +The project must attempt to disprove its own central claim. | ||||
| 1226 | + | ||||
| 1227 | +Required falsifications include: | ||||
| 1228 | + | ||||
| 1229 | +- no systematic response before the source shock; | ||||
| 1230 | +- weak propagation through randomized networks; | ||||
| 1231 | +- weaker response among economically unrelated stocks; | ||||
| 1232 | +- stronger response after genuine shocks than matched placebo times; | ||||
| 1233 | +- no apparent secular acceleration caused solely by changing sample size; | ||||
| 1234 | +- no apparent acceleration caused solely by timestamp precision or coverage changes; | ||||
| 1235 | +- no result driven by a few crisis days; | ||||
| 1236 | +- no result driven by the largest technology stocks; | ||||
| 1237 | +- no result driven solely by ETFs; | ||||
| 1238 | +- no result generated mechanically by market-factor construction; | ||||
| 1239 | +- no result driven by corporate actions. | ||||
| 1240 | + | ||||
| 1241 | +If a falsification fails, do not hide it. Reassess the claim. | ||||
| 1242 | + | ||||
| 1243 | +--- | ||||
| 1244 | + | ||||
| 1245 | +# 17. Descriptive tables required | ||||
| 1246 | + | ||||
| 1247 | +Generate the following main-paper candidates. | ||||
| 1248 | + | ||||
| 1249 | +## Table I — Sample construction | ||||
| 1250 | + | ||||
| 1251 | +Include by decade or period: | ||||
| 1252 | + | ||||
| 1253 | +- raw rows; | ||||
| 1254 | +- raw symbols; | ||||
| 1255 | +- valid trading days; | ||||
| 1256 | +- duplicate removals; | ||||
| 1257 | +- invalid OHLC removals; | ||||
| 1258 | +- suspected corporate-action exclusions; | ||||
| 1259 | +- final stock-minute observations; | ||||
| 1260 | +- final securities; | ||||
| 1261 | +- median valid minutes per stock-day. | ||||
| 1262 | + | ||||
| 1263 | +## Table II — Summary statistics | ||||
| 1264 | + | ||||
| 1265 | +For core variables: | ||||
| 1266 | + | ||||
| 1267 | +- mean; | ||||
| 1268 | +- standard deviation; | ||||
| 1269 | +- p1; | ||||
| 1270 | +- p5; | ||||
| 1271 | +- median; | ||||
| 1272 | +- p95; | ||||
| 1273 | +- p99; | ||||
| 1274 | +- number of observations. | ||||
| 1275 | + | ||||
| 1276 | +Report at the economically appropriate unit to avoid meaningless precision. | ||||
| 1277 | + | ||||
| 1278 | +## Table III — Characteristics of source shocks | ||||
| 1279 | + | ||||
| 1280 | +Compare: | ||||
| 1281 | + | ||||
| 1282 | +- positive and negative shocks; | ||||
| 1283 | +- low- and high-volatility states; | ||||
| 1284 | +- early and late sample; | ||||
| 1285 | +- cascade and non-cascade shocks. | ||||
| 1286 | + | ||||
| 1287 | +## Table IV — Baseline propagation | ||||
| 1288 | + | ||||
| 1289 | +Show horizon-specific coefficients for breadth, intensity, and persistence. | ||||
| 1290 | + | ||||
| 1291 | +## Table V — Nonlinearity and asymmetry | ||||
| 1292 | + | ||||
| 1293 | +Show shock-size bins, negative interaction, and market-state interactions. | ||||
| 1294 | + | ||||
| 1295 | +## Table VI — Evolution over time | ||||
| 1296 | + | ||||
| 1297 | +Show flexible period or year interactions and tests of equality. | ||||
| 1298 | + | ||||
| 1299 | +## Table VII — Network mechanisms | ||||
| 1300 | + | ||||
| 1301 | +Compare connected and unconnected receivers and transmitter centrality. | ||||
| 1302 | + | ||||
| 1303 | +## Table VIII — Identification and placebo tests | ||||
| 1304 | + | ||||
| 1305 | +Include macro exclusions, matched placebo times, and permuted networks. | ||||
| 1306 | + | ||||
| 1307 | +Keep the main manuscript selective. Move secondary tables to the Internet Appendix. | ||||
| 1308 | + | ||||
| 1309 | +--- | ||||
| 1310 | + | ||||
| 1311 | +# 18. Figures required | ||||
| 1312 | + | ||||
| 1313 | +Create journal-quality figures in PDF and high-resolution PNG. | ||||
| 1314 | + | ||||
| 1315 | +## Figure 1 — Data coverage | ||||
| 1316 | + | ||||
| 1317 | +Panels may show: | ||||
| 1318 | + | ||||
| 1319 | +- number of securities by year; | ||||
| 1320 | +- number of observations by year; | ||||
| 1321 | +- median bars per stock-day; | ||||
| 1322 | +- missingness rate. | ||||
| 1323 | + | ||||
| 1324 | +## Figure 2 — Intraday seasonality | ||||
| 1325 | + | ||||
| 1326 | +Show minute-of-day patterns for: | ||||
| 1327 | + | ||||
| 1328 | +- volatility; | ||||
| 1329 | +- volume; | ||||
| 1330 | +- range; | ||||
| 1331 | +- shock incidence. | ||||
| 1332 | + | ||||
| 1333 | +## Figure 3 — Anatomy of a representative cascade | ||||
| 1334 | + | ||||
| 1335 | +A carefully selected event visualization with: | ||||
| 1336 | + | ||||
| 1337 | +- source shock; | ||||
| 1338 | +- sector response; | ||||
| 1339 | +- market breadth; | ||||
| 1340 | +- network diffusion; | ||||
| 1341 | +- confidence or placebo envelope where possible. | ||||
| 1342 | + | ||||
| 1343 | +Do not cherry-pick without a transparent selection rule. | ||||
| 1344 | + | ||||
| 1345 | +## Figure 4 — Impulse responses | ||||
| 1346 | + | ||||
| 1347 | +Local-projection responses over 1–120 minutes for: | ||||
| 1348 | + | ||||
| 1349 | +- breadth; | ||||
| 1350 | +- intensity; | ||||
| 1351 | +- signed returns; | ||||
| 1352 | +- volatility. | ||||
| 1353 | + | ||||
| 1354 | +## Figure 5 — Nonlinear propagation | ||||
| 1355 | + | ||||
| 1356 | +Plot propagation against source-shock magnitude with confidence bands. | ||||
| 1357 | + | ||||
| 1358 | +## Figure 6 — Positive-negative asymmetry | ||||
| 1359 | + | ||||
| 1360 | +Show comparable positive and negative shocks. | ||||
| 1361 | + | ||||
| 1362 | +## Figure 7 — Evolution over time | ||||
| 1363 | + | ||||
| 1364 | +Show annual or rolling estimates of propagation speed and breadth. | ||||
| 1365 | + | ||||
| 1366 | +## Figure 8 — Network position and cascade risk | ||||
| 1367 | + | ||||
| 1368 | +Show economically interpretable bins of lagged source centrality. | ||||
| 1369 | + | ||||
| 1370 | +## Figure 9 — Market-state dependence | ||||
| 1371 | + | ||||
| 1372 | +Compare calm and stressed states. | ||||
| 1373 | + | ||||
| 1374 | +## Figure 10 — Falsification evidence | ||||
| 1375 | + | ||||
| 1376 | +Real versus matched placebo and real versus permuted-network responses. | ||||
| 1377 | + | ||||
| 1378 | +--- | ||||
| 1379 | + | ||||
| 1380 | +# 19. Figure style: Journal of Finance quality | ||||
| 1381 | + | ||||
| 1382 | +The phrase “JF style” means restrained, legible, publication-quality academic graphics, not imitation of proprietary branding. | ||||
| 1383 | + | ||||
| 1384 | +Use: | ||||
| 1385 | + | ||||
| 1386 | +- vector PDF as the primary format; | ||||
| 1387 | +- embedded fonts; | ||||
| 1388 | +- white background; | ||||
| 1389 | +- minimal chart ink; | ||||
| 1390 | +- no 3D effects; | ||||
| 1391 | +- no gradients; | ||||
| 1392 | +- no decorative icons; | ||||
| 1393 | +- no unnecessary borders; | ||||
| 1394 | +- no chart titles inside the plotting region unless essential; | ||||
| 1395 | +- concise axis labels; | ||||
| 1396 | +- consistent font family and sizing; | ||||
| 1397 | +- grayscale-safe line types and markers; | ||||
| 1398 | +- colorblind-safe colors when color is needed; | ||||
| 1399 | +- direct labels where clearer than legends; | ||||
| 1400 | +- confidence bands with restrained opacity; | ||||
| 1401 | +- panel labels `(a)`, `(b)`, etc.; | ||||
| 1402 | +- identical scales across comparable panels; | ||||
| 1403 | +- economically meaningful tick marks; | ||||
| 1404 | +- no scientific notation unless unavoidable; | ||||
| 1405 | +- no excessive decimal places. | ||||
| 1406 | + | ||||
| 1407 | +Every figure must include a LaTeX note explaining: | ||||
| 1408 | + | ||||
| 1409 | +- sample; | ||||
| 1410 | +- variable definitions; | ||||
| 1411 | +- estimation method; | ||||
| 1412 | +- confidence intervals; | ||||
| 1413 | +- clustering or bootstrap; | ||||
| 1414 | +- normalization; | ||||
| 1415 | +- exclusions. | ||||
| 1416 | + | ||||
| 1417 | +Save source data for every figure as Parquet or CSV in: | ||||
| 1418 | + | ||||
| 1419 | +```text | ||||
| 1420 | +outputs/figures/data/ | ||||
| 1421 | +``` | ||||
| 1422 | + | ||||
| 1423 | +A figure must be reproducible from its source-data file without rerunning the entire empirical pipeline. | ||||
| 1424 | + | ||||
| 1425 | +--- | ||||
| 1426 | + | ||||
| 1427 | +# 20. LaTeX table style | ||||
| 1428 | + | ||||
| 1429 | +Use `booktabs`. Avoid vertical rules. Avoid excessive horizontal rules. | ||||
| 1430 | + | ||||
| 1431 | +Preferred packages: | ||||
| 1432 | + | ||||
| 1433 | +```latex | ||||
| 1434 | +\usepackage{booktabs} | ||||
| 1435 | +\usepackage{threeparttable} | ||||
| 1436 | +\usepackage{siunitx} | ||||
| 1437 | +\usepackage{adjustbox} | ||||
| 1438 | +\usepackage{longtable} | ||||
| 1439 | +\usepackage{tabularx} | ||||
| 1440 | +\usepackage{pdflscape} | ||||
| 1441 | +``` | ||||
| 1442 | + | ||||
| 1443 | +Requirements: | ||||
| 1444 | + | ||||
| 1445 | +- decimal alignment; | ||||
| 1446 | +- consistent coefficient precision; | ||||
| 1447 | +- standard errors in parentheses; | ||||
| 1448 | +- significance stars only as a secondary visual convention; | ||||
| 1449 | +- report exact or thresholded p-values where useful; | ||||
| 1450 | +- clearly label fixed effects; | ||||
| 1451 | +- clearly label clustering; | ||||
| 1452 | +- include sample size; | ||||
| 1453 | +- include within or adjusted \(R^2\) as appropriate; | ||||
| 1454 | +- include dependent-variable mean when informative; | ||||
| 1455 | +- include economic magnitude; | ||||
| 1456 | +- use clear panel headings; | ||||
| 1457 | +- use detailed table notes; | ||||
| 1458 | +- avoid shrinking text below readability. | ||||
| 1459 | + | ||||
| 1460 | +Do not use stars as the main argument. Emphasize coefficient magnitude, confidence intervals, and economic interpretation. | ||||
| 1461 | + | ||||
| 1462 | +Generate each table in two forms: | ||||
| 1463 | + | ||||
| 1464 | +1. standalone `.tex`; | ||||
| 1465 | +2. machine-readable `.csv` or `.parquet`. | ||||
| 1466 | + | ||||
| 1467 | +All table numbers must come directly from stored estimation objects. | ||||
| 1468 | + | ||||
| 1469 | +--- | ||||
| 1470 | + | ||||
| 1471 | +# 21. Literature review standard | ||||
| 1472 | + | ||||
| 1473 | +The literature review must be comprehensive, current, accurate, and organized around the paper’s contribution. It must not be a list of summaries. | ||||
| 1474 | + | ||||
| 1475 | +## 21.1 Literature streams | ||||
| 1476 | + | ||||
| 1477 | +Build a literature map covering at least: | ||||
| 1478 | + | ||||
| 1479 | +1. market liquidity and liquidity risk; | ||||
| 1480 | +2. commonality in liquidity; | ||||
| 1481 | +3. market microstructure and price discovery; | ||||
| 1482 | +4. high-frequency trading and algorithmic trading; | ||||
| 1483 | +5. market fragility and flash events; | ||||
| 1484 | +6. cross-asset price impact and cross-impact; | ||||
| 1485 | +7. volatility spillovers and contagion networks; | ||||
| 1486 | +8. lead-lag relationships; | ||||
| 1487 | +9. intraday jumps; | ||||
| 1488 | +10. Hawkes processes and self-excitation; | ||||
| 1489 | +11. factor models for high-frequency returns; | ||||
| 1490 | +12. electronic-market design and fragmentation; | ||||
| 1491 | +13. ETF, passive, and portfolio-trading effects; | ||||
| 1492 | +14. systemic risk and network centrality; | ||||
| 1493 | +15. machine learning in market microstructure; | ||||
| 1494 | +16. measurement using OHLCV versus trades and quotes. | ||||
| 1495 | + | ||||
| 1496 | +## 21.2 Source quality hierarchy | ||||
| 1497 | + | ||||
| 1498 | +Prioritize: | ||||
| 1499 | + | ||||
| 1500 | +1. published articles in leading finance, economics, econometrics, and statistics journals; | ||||
| 1501 | +2. authoritative working papers from NBER, CEPR, central banks, BIS, and established scholars; | ||||
| 1502 | +3. official exchange, SEC, Federal Reserve, and regulatory documents; | ||||
| 1503 | +4. recent working papers only when directly relevant and clearly labeled as unpublished. | ||||
| 1504 | + | ||||
| 1505 | +Do not rely on blogs, generic websites, generated summaries, or low-quality outlets for core claims. | ||||
| 1506 | + | ||||
| 1507 | +## 21.3 Citation verification | ||||
| 1508 | + | ||||
| 1509 | +For every cited work: | ||||
| 1510 | + | ||||
| 1511 | +- verify title; | ||||
| 1512 | +- verify authors; | ||||
| 1513 | +- verify year; | ||||
| 1514 | +- verify journal or working-paper series; | ||||
| 1515 | +- verify volume, issue, and pages where applicable; | ||||
| 1516 | +- verify DOI where available; | ||||
| 1517 | +- verify that the paper actually supports the sentence; | ||||
| 1518 | +- save the source and citation metadata; | ||||
| 1519 | +- never cite a work based only on another paper’s bibliography. | ||||
| 1520 | + | ||||
| 1521 | +Maintain `docs/LITERATURE_MAP.md` with columns: | ||||
| 1522 | + | ||||
| 1523 | +- citation key; | ||||
| 1524 | +- full citation; | ||||
| 1525 | +- literature stream; | ||||
| 1526 | +- research question; | ||||
| 1527 | +- data; | ||||
| 1528 | +- frequency; | ||||
| 1529 | +- identification; | ||||
| 1530 | +- main result; | ||||
| 1531 | +- relevance; | ||||
| 1532 | +- difference from our paper; | ||||
| 1533 | +- verified source; | ||||
| 1534 | +- verification date. | ||||
| 1535 | + | ||||
| 1536 | +## 21.4 Literature review argument | ||||
| 1537 | + | ||||
| 1538 | +The review should establish: | ||||
| 1539 | + | ||||
| 1540 | +1. liquidity and volatility exhibit common components; | ||||
| 1541 | +2. shocks can transmit across assets through information and trading channels; | ||||
| 1542 | +3. high-frequency market structure may improve normal-times efficiency while creating tail fragility; | ||||
| 1543 | +4. prior work often studies limited instruments, shorter samples, quotes/order books, particular episodes, or lower-dimensional networks; | ||||
| 1544 | +5. the present paper contributes a long historical, broad cross-section of minute-level U.S. equity data; | ||||
| 1545 | +6. OHLCV breadth comes with measurement limitations; | ||||
| 1546 | +7. the paper’s novelty lies in the joint analysis of speed, breadth, persistence, asymmetry, time evolution, and network conditioning. | ||||
| 1547 | + | ||||
| 1548 | +Do not overclaim uniqueness until a documented literature search confirms it. | ||||
| 1549 | + | ||||
| 1550 | +--- | ||||
| 1551 | + | ||||
| 1552 | +# 22. Paper outline | ||||
| 1553 | + | ||||
| 1554 | +The paper must be written in English. | ||||
| 1555 | + | ||||
| 1556 | +## 22.1 Abstract | ||||
| 1557 | + | ||||
| 1558 | +Target approximately 120–180 words unless the current submission rules require otherwise. | ||||
| 1559 | + | ||||
| 1560 | +The abstract must contain: | ||||
| 1561 | + | ||||
| 1562 | +1. question; | ||||
| 1563 | +2. data; | ||||
| 1564 | +3. method; | ||||
| 1565 | +4. central result; | ||||
| 1566 | +5. mechanism; | ||||
| 1567 | +6. implication. | ||||
| 1568 | + | ||||
| 1569 | +Do not include vague claims such as “significant implications.” State the economic fact. | ||||
| 1570 | + | ||||
| 1571 | +## 22.2 Introduction | ||||
| 1572 | + | ||||
| 1573 | +The introduction should be approximately 4–6 manuscript pages and follow this logic: | ||||
| 1574 | + | ||||
| 1575 | +### Paragraph 1 — Economic problem | ||||
| 1576 | +Explain why intraday propagation matters for price discovery, liquidity, execution, and systemic stability. | ||||
| 1577 | + | ||||
| 1578 | +### Paragraph 2 — Tension | ||||
| 1579 | +Present the core tension: faster and more liquid markets may absorb ordinary information efficiently but transmit extreme shocks rapidly. | ||||
| 1580 | + | ||||
| 1581 | +### Paragraph 3 — Research question | ||||
| 1582 | +State exactly what the paper asks. | ||||
| 1583 | + | ||||
| 1584 | +### Paragraph 4 — Data and empirical setting | ||||
| 1585 | +Describe the broad minute-level panel, while flagging that validation determines the final sample. | ||||
| 1586 | + | ||||
| 1587 | +### Paragraphs 5–7 — Main findings | ||||
| 1588 | +Present only verified findings, including economic magnitudes and uncertainty. | ||||
| 1589 | + | ||||
| 1590 | +### Paragraph 8 — Identification | ||||
| 1591 | +Explain how the paper distinguishes propagation from common information. | ||||
| 1592 | + | ||||
| 1593 | +### Paragraph 9 — Mechanisms | ||||
| 1594 | +Summarize network, market-state, and asymmetry evidence. | ||||
| 1595 | + | ||||
| 1596 | +### Paragraphs 10–12 — Contributions | ||||
| 1597 | +State contributions relative to specific literature streams. | ||||
| 1598 | + | ||||
| 1599 | +### Final paragraph — Road map | ||||
| 1600 | +Keep it brief. | ||||
| 1601 | + | ||||
| 1602 | +The introduction must not read like a technical report. It must build an economic argument. | ||||
| 1603 | + | ||||
| 1604 | +## 22.3 Literature review | ||||
| 1605 | + | ||||
| 1606 | +Integrate literature with hypotheses and contributions. Avoid a long disconnected catalog. | ||||
| 1607 | + | ||||
| 1608 | +## 22.4 Data | ||||
| 1609 | + | ||||
| 1610 | +Explain: | ||||
| 1611 | + | ||||
| 1612 | +- provenance; | ||||
| 1613 | +- raw structure; | ||||
| 1614 | +- coverage; | ||||
| 1615 | +- audit; | ||||
| 1616 | +- filters; | ||||
| 1617 | +- timestamp convention; | ||||
| 1618 | +- corporate-action handling; | ||||
| 1619 | +- security identity; | ||||
| 1620 | +- survivorship concerns; | ||||
| 1621 | +- descriptive statistics; | ||||
| 1622 | +- limitations. | ||||
| 1623 | + | ||||
| 1624 | +## 22.5 Measurement | ||||
| 1625 | + | ||||
| 1626 | +Define: | ||||
| 1627 | + | ||||
| 1628 | +- residual shocks; | ||||
| 1629 | +- propagation outcomes; | ||||
| 1630 | +- networks; | ||||
| 1631 | +- market states; | ||||
| 1632 | +- centrality; | ||||
| 1633 | +- cascade thresholds. | ||||
| 1634 | + | ||||
| 1635 | +## 22.6 Empirical design | ||||
| 1636 | + | ||||
| 1637 | +Explain: | ||||
| 1638 | + | ||||
| 1639 | +- local projections; | ||||
| 1640 | +- event-study design; | ||||
| 1641 | +- fixed effects; | ||||
| 1642 | +- inference; | ||||
| 1643 | +- timing; | ||||
| 1644 | +- identification assumptions; | ||||
| 1645 | +- threats. | ||||
| 1646 | + | ||||
| 1647 | +## 22.7 Results | ||||
| 1648 | + | ||||
| 1649 | +Organize by economic question, not by code execution order. | ||||
| 1650 | + | ||||
| 1651 | +Suggested sequence: | ||||
| 1652 | + | ||||
| 1653 | +1. basic propagation; | ||||
| 1654 | +2. nonlinear threshold; | ||||
| 1655 | +3. asymmetry; | ||||
| 1656 | +4. time evolution; | ||||
| 1657 | +5. network mechanism; | ||||
| 1658 | +6. market-state dependence; | ||||
| 1659 | +7. identification and placebo evidence. | ||||
| 1660 | + | ||||
| 1661 | +## 22.8 Robustness | ||||
| 1662 | + | ||||
| 1663 | +Keep the main text focused. Refer to a detailed Internet Appendix. | ||||
| 1664 | + | ||||
| 1665 | +## 22.9 Conclusion | ||||
| 1666 | + | ||||
| 1667 | +Do not merely summarize. State: | ||||
| 1668 | + | ||||
| 1669 | +- what was learned; | ||||
| 1670 | +- what remains unidentified; | ||||
| 1671 | +- implications for market design and risk monitoring; | ||||
| 1672 | +- limits of OHLCV data; | ||||
| 1673 | +- future work with quote and order-book data. | ||||
| 1674 | + | ||||
| 1675 | +--- | ||||
| 1676 | + | ||||
| 1677 | +# 23. Writing standards | ||||
| 1678 | + | ||||
| 1679 | +The paper must read like a finance paper, not AI-generated prose. | ||||
| 1680 | + | ||||
| 1681 | +Use: | ||||
| 1682 | + | ||||
| 1683 | +- precise claims; | ||||
| 1684 | +- active voice where natural; | ||||
| 1685 | +- disciplined paragraphs; | ||||
| 1686 | +- explicit economic magnitudes; | ||||
| 1687 | +- clear transitions; | ||||
| 1688 | +- restrained tone; | ||||
| 1689 | +- correct terminology; | ||||
| 1690 | +- consistent notation. | ||||
| 1691 | + | ||||
| 1692 | +Avoid: | ||||
| 1693 | + | ||||
| 1694 | +- hype; | ||||
| 1695 | +- “revolutionary”; | ||||
| 1696 | +- “groundbreaking” unless quoting; | ||||
| 1697 | +- “unprecedented” without proof; | ||||
| 1698 | +- “leveraging” as filler; | ||||
| 1699 | +- “delve”; | ||||
| 1700 | +- “multifaceted”; | ||||
| 1701 | +- repeated road maps; | ||||
| 1702 | +- excessive bullet points in the manuscript; | ||||
| 1703 | +- paragraphs that merely describe tables; | ||||
| 1704 | +- causal verbs without identification; | ||||
| 1705 | +- statements that statistical significance proves importance. | ||||
| 1706 | + | ||||
| 1707 | +Every empirical paragraph should answer: | ||||
| 1708 | + | ||||
| 1709 | +1. What is estimated? | ||||
| 1710 | +2. What is the sign and magnitude? | ||||
| 1711 | +3. How uncertain is it? | ||||
| 1712 | +4. What is the economic interpretation? | ||||
| 1713 | +5. Which competing explanation remains? | ||||
| 1714 | +6. Which robustness test addresses it? | ||||
| 1715 | + | ||||
| 1716 | +--- | ||||
| 1717 | + | ||||
| 1718 | +# 24. JF submission preparation | ||||
| 1719 | + | ||||
| 1720 | +At the time of final preparation, verify the current official Journal of Finance submission instructions. | ||||
| 1721 | + | ||||
| 1722 | +The working format should conservatively use: | ||||
| 1723 | + | ||||
| 1724 | +- 12-point font; | ||||
| 1725 | +- at least 1.5 line spacing; | ||||
| 1726 | +- readable margins; | ||||
| 1727 | +- page numbers; | ||||
| 1728 | +- anonymous manuscript version; | ||||
| 1729 | +- separate title page if required; | ||||
| 1730 | +- main manuscript no longer than the current JF limit; | ||||
| 1731 | +- separate Internet Appendix; | ||||
| 1732 | +- consistent references; | ||||
| 1733 | +- tables and figures placed according to current instructions. | ||||
| 1734 | + | ||||
| 1735 | +Do not assume old formatting rules remain current. Record the date and source of the final guideline check in: | ||||
| 1736 | + | ||||
| 1737 | +```text | ||||
| 1738 | +docs/DECISION_LOG.md | ||||
| 1739 | +``` | ||||
| 1740 | + | ||||
| 1741 | +Create: | ||||
| 1742 | + | ||||
| 1743 | +```text | ||||
| 1744 | +outputs/release/ | ||||
| 1745 | +├── manuscript_anonymous.pdf | ||||
| 1746 | +├── manuscript_named.pdf | ||||
| 1747 | +├── internet_appendix.pdf | ||||
| 1748 | +├── title_page.pdf | ||||
| 1749 | +├── cover_letter.tex | ||||
| 1750 | +├── cover_letter.pdf | ||||
| 1751 | +├── source_archive.zip | ||||
| 1752 | +├── replication_manifest.json | ||||
| 1753 | +└── submission_checklist.md | ||||
| 1754 | +``` | ||||
| 1755 | + | ||||
| 1756 | +The cover letter must be factual and restrained. Do not claim acceptance probability or editorial fit without evidence. | ||||
| 1757 | + | ||||
| 1758 | +--- | ||||
| 1759 | + | ||||
| 1760 | +# 25. Main paper versus Internet Appendix | ||||
| 1761 | + | ||||
| 1762 | +## Main paper | ||||
| 1763 | + | ||||
| 1764 | +Reserve for: | ||||
| 1765 | + | ||||
| 1766 | +- core question; | ||||
| 1767 | +- central descriptive evidence; | ||||
| 1768 | +- primary identification; | ||||
| 1769 | +- main economic mechanism; | ||||
| 1770 | +- essential robustness; | ||||
| 1771 | +- clear contribution. | ||||
| 1772 | + | ||||
| 1773 | +## Internet Appendix | ||||
| 1774 | + | ||||
| 1775 | +Include: | ||||
| 1776 | + | ||||
| 1777 | +- extended data audit; | ||||
| 1778 | +- full sample-construction details; | ||||
| 1779 | +- additional variable definitions; | ||||
| 1780 | +- alternative filters; | ||||
| 1781 | +- alternative networks; | ||||
| 1782 | +- alternative thresholds; | ||||
| 1783 | +- additional event studies; | ||||
| 1784 | +- placebo distributions; | ||||
| 1785 | +- machine-learning architecture; | ||||
| 1786 | +- hyperparameters; | ||||
| 1787 | +- computational details; | ||||
| 1788 | +- additional tables and figures; | ||||
| 1789 | +- proofs or derivations; | ||||
| 1790 | +- replication details. | ||||
| 1791 | + | ||||
| 1792 | +Every appendix item must be referenced from the main paper where relevant. | ||||
| 1793 | + | ||||
| 1794 | +--- | ||||
| 1795 | + | ||||
| 1796 | +# 26. Reproducibility and provenance | ||||
| 1797 | + | ||||
| 1798 | +## 26.1 Configuration | ||||
| 1799 | + | ||||
| 1800 | +All parameters must live in versioned YAML files, not scattered through scripts. | ||||
| 1801 | + | ||||
| 1802 | +## 26.2 Random seeds | ||||
| 1803 | + | ||||
| 1804 | +Set and log seeds for: | ||||
| 1805 | + | ||||
| 1806 | +- sampling; | ||||
| 1807 | +- bootstraps; | ||||
| 1808 | +- permutations; | ||||
| 1809 | +- machine learning; | ||||
| 1810 | +- graph estimation; | ||||
| 1811 | +- simulations. | ||||
| 1812 | + | ||||
| 1813 | +## 26.3 Versioning | ||||
| 1814 | + | ||||
| 1815 | +Record: | ||||
| 1816 | + | ||||
| 1817 | +- Git commit; | ||||
| 1818 | +- Python version; | ||||
| 1819 | +- package versions; | ||||
| 1820 | +- OS; | ||||
| 1821 | +- hardware; | ||||
| 1822 | +- dataset revision; | ||||
| 1823 | +- external-data revision; | ||||
| 1824 | +- command line; | ||||
| 1825 | +- start and end time. | ||||
| 1826 | + | ||||
| 1827 | +## 26.4 Data lineage | ||||
| 1828 | + | ||||
| 1829 | +Each processed file must record: | ||||
| 1830 | + | ||||
| 1831 | +- parent inputs; | ||||
| 1832 | +- transformation version; | ||||
| 1833 | +- filters; | ||||
| 1834 | +- row counts before and after; | ||||
| 1835 | +- creation timestamp; | ||||
| 1836 | +- code commit. | ||||
| 1837 | + | ||||
| 1838 | +## 26.5 No manual numerical edits | ||||
| 1839 | + | ||||
| 1840 | +LaTeX tables, abstract numbers, introduction magnitudes, and conclusion numbers must be populated from a central results registry such as: | ||||
| 1841 | + | ||||
| 1842 | +```text | ||||
| 1843 | +outputs/estimates/results_registry.json | ||||
| 1844 | +``` | ||||
| 1845 | + | ||||
| 1846 | +Implement macros such as: | ||||
| 1847 | + | ||||
| 1848 | +```latex | ||||
| 1849 | +\newcommand{\MainBreadthEffect}{...} | ||||
| 1850 | +``` | ||||
| 1851 | + | ||||
| 1852 | +generated automatically from verified outputs. | ||||
| 1853 | + | ||||
| 1854 | +--- | ||||
| 1855 | + | ||||
| 1856 | +# 27. Compute strategy for a cluster | ||||
| 1857 | + | ||||
| 1858 | +The pipeline must be scalable but safe. | ||||
| 1859 | + | ||||
| 1860 | +## 27.1 Preferred data tools | ||||
| 1861 | + | ||||
| 1862 | +Consider: | ||||
| 1863 | + | ||||
| 1864 | +- PyArrow; | ||||
| 1865 | +- Polars lazy execution; | ||||
| 1866 | +- DuckDB; | ||||
| 1867 | +- Dask or Ray only where they add value; | ||||
| 1868 | +- partitioned Parquet; | ||||
| 1869 | +- predicate pushdown; | ||||
| 1870 | +- memory-mapped reads; | ||||
| 1871 | +- streaming aggregations. | ||||
| 1872 | + | ||||
| 1873 | +Avoid loading the full dataset into RAM. | ||||
| 1874 | + | ||||
| 1875 | +## 27.2 Partitioning | ||||
| 1876 | + | ||||
| 1877 | +Partition processed data by a combination of: | ||||
| 1878 | + | ||||
| 1879 | +- year; | ||||
| 1880 | +- month; | ||||
| 1881 | +- trading date; | ||||
| 1882 | +- symbol bucket. | ||||
| 1883 | + | ||||
| 1884 | +Select partitions based on dominant query patterns. | ||||
| 1885 | + | ||||
| 1886 | +## 27.3 Distributed jobs | ||||
| 1887 | + | ||||
| 1888 | +Every distributed task must: | ||||
| 1889 | + | ||||
| 1890 | +- be idempotent; | ||||
| 1891 | +- write to temporary paths; | ||||
| 1892 | +- atomically rename on success; | ||||
| 1893 | +- save checkpoints; | ||||
| 1894 | +- avoid multiple nodes writing the same final file; | ||||
| 1895 | +- emit structured logs; | ||||
| 1896 | +- support retry; | ||||
| 1897 | +- validate output before success. | ||||
| 1898 | + | ||||
| 1899 | +## 27.4 Resource benchmarking | ||||
| 1900 | + | ||||
| 1901 | +Before a full run: | ||||
| 1902 | + | ||||
| 1903 | +1. benchmark one month; | ||||
| 1904 | +2. benchmark one year; | ||||
| 1905 | +3. estimate CPU hours; | ||||
| 1906 | +4. estimate memory; | ||||
| 1907 | +5. estimate temporary storage; | ||||
| 1908 | +6. estimate final storage; | ||||
| 1909 | +7. record in `docs/COMPUTE_LOG.md`. | ||||
| 1910 | + | ||||
| 1911 | +Optimization must not change estimands or silently alter precision. | ||||
| 1912 | + | ||||
| 1913 | +--- | ||||
| 1914 | + | ||||
| 1915 | +# 28. Testing and validation | ||||
| 1916 | + | ||||
| 1917 | +## 28.1 Unit tests | ||||
| 1918 | + | ||||
| 1919 | +Test: | ||||
| 1920 | + | ||||
| 1921 | +- timestamp conversion; | ||||
| 1922 | +- session assignment; | ||||
| 1923 | +- return calculation; | ||||
| 1924 | +- shock detection; | ||||
| 1925 | +- lag discipline; | ||||
| 1926 | +- no future-data leakage; | ||||
| 1927 | +- network-window cutoffs; | ||||
| 1928 | +- breadth denominator; | ||||
| 1929 | +- session-boundary horizons; | ||||
| 1930 | +- table formatting. | ||||
| 1931 | + | ||||
| 1932 | +## 28.2 Synthetic-data tests | ||||
| 1933 | + | ||||
| 1934 | +Generate small synthetic panels with known: | ||||
| 1935 | + | ||||
| 1936 | +- common shocks; | ||||
| 1937 | +- idiosyncratic shocks; | ||||
| 1938 | +- directed propagation; | ||||
| 1939 | +- no propagation; | ||||
| 1940 | +- positive-negative asymmetry; | ||||
| 1941 | +- missing bars; | ||||
| 1942 | +- split-like jumps. | ||||
| 1943 | + | ||||
| 1944 | +Confirm that the pipeline recovers the intended patterns and rejects false ones. | ||||
| 1945 | + | ||||
| 1946 | +## 28.3 Release validation | ||||
| 1947 | + | ||||
| 1948 | +The release script must fail if: | ||||
| 1949 | + | ||||
| 1950 | +- a table references a missing result; | ||||
| 1951 | +- a figure is missing source data; | ||||
| 1952 | +- LaTeX does not compile; | ||||
| 1953 | +- citations are unresolved; | ||||
| 1954 | +- labels are duplicated; | ||||
| 1955 | +- page count exceeds the current target; | ||||
| 1956 | +- anonymous PDF contains author-identifying text; | ||||
| 1957 | +- manuscript claims disagree with the results registry; | ||||
| 1958 | +- data revision is not pinned; | ||||
| 1959 | +- tests fail. | ||||
| 1960 | + | ||||
| 1961 | +--- | ||||
| 1962 | + | ||||
| 1963 | +# 29. Decision log | ||||
| 1964 | + | ||||
| 1965 | +Maintain `docs/DECISION_LOG.md`. | ||||
| 1966 | + | ||||
| 1967 | +For every major choice, record: | ||||
| 1968 | + | ||||
| 1969 | +- date; | ||||
| 1970 | +- decision; | ||||
| 1971 | +- alternatives considered; | ||||
| 1972 | +- empirical reason; | ||||
| 1973 | +- theoretical reason; | ||||
| 1974 | +- effect on interpretation; | ||||
| 1975 | +- whether pre-specified or data-driven; | ||||
| 1976 | +- code/config reference. | ||||
| 1977 | + | ||||
| 1978 | +Important decisions include: | ||||
| 1979 | + | ||||
| 1980 | +- timestamp convention; | ||||
| 1981 | +- regular-session definition; | ||||
| 1982 | +- security filters; | ||||
| 1983 | +- shock threshold; | ||||
| 1984 | +- network window; | ||||
| 1985 | +- factor model; | ||||
| 1986 | +- clustering; | ||||
| 1987 | +- periodization; | ||||
| 1988 | +- figure selection; | ||||
| 1989 | +- main versus appendix placement. | ||||
| 1990 | + | ||||
| 1991 | +--- | ||||
| 1992 | + | ||||
| 1993 | +# 30. Minimum deliverables for the first phase | ||||
| 1994 | + | ||||
| 1995 | +The first phase is complete only when all the following exist. | ||||
| 1996 | + | ||||
| 1997 | +## Data acquisition | ||||
| 1998 | + | ||||
| 1999 | +- [ ] repository metadata report; | ||||
| 2000 | +- [ ] pinned dataset revision; | ||||
| 2001 | +- [ ] storage estimate; | ||||
| 2002 | +- [ ] resumable downloader; | ||||
| 2003 | +- [ ] raw manifest; | ||||
| 2004 | +- [ ] checksum verification; | ||||
| 2005 | +- [ ] three-month pilot sample; | ||||
| 2006 | +- [ ] full-download plan. | ||||
| 2007 | + | ||||
| 2008 | +## Audit | ||||
| 2009 | + | ||||
| 2010 | +- [ ] schema report; | ||||
| 2011 | +- [ ] timestamp report; | ||||
| 2012 | +- [ ] calendar report; | ||||
| 2013 | +- [ ] OHLC validity report; | ||||
| 2014 | +- [ ] duplicate report; | ||||
| 2015 | +- [ ] missingness report; | ||||
| 2016 | +- [ ] corporate-action diagnostic; | ||||
| 2017 | +- [ ] security-universe diagnostic; | ||||
| 2018 | +- [ ] survivorship assessment; | ||||
| 2019 | +- [ ] limitations memo. | ||||
| 2020 | + | ||||
| 2021 | +## Prototype analysis | ||||
| 2022 | + | ||||
| 2023 | +- [ ] clean pilot panel; | ||||
| 2024 | +- [ ] intraday seasonality figure; | ||||
| 2025 | +- [ ] sample-coverage figure; | ||||
| 2026 | +- [ ] preliminary shock definition; | ||||
| 2027 | +- [ ] preliminary cascade measure; | ||||
| 2028 | +- [ ] one transparent baseline regression; | ||||
| 2029 | +- [ ] one placebo test; | ||||
| 2030 | +- [ ] one LaTeX summary-statistics table; | ||||
| 2031 | +- [ ] one LaTeX baseline-results table. | ||||
| 2032 | + | ||||
| 2033 | +## Paper infrastructure | ||||
| 2034 | + | ||||
| 2035 | +- [ ] compiling `main.tex`; | ||||
| 2036 | +- [ ] compiling Internet Appendix; | ||||
| 2037 | +- [ ] verified bibliography workflow; | ||||
| 2038 | +- [ ] literature map; | ||||
| 2039 | +- [ ] introduction outline; | ||||
| 2040 | +- [ ] data-section draft based only on verified facts; | ||||
| 2041 | +- [ ] automated figure and table inclusion. | ||||
| 2042 | + | ||||
| 2043 | +--- | ||||
| 2044 | + | ||||
| 2045 | +# 31. Stop conditions | ||||
| 2046 | + | ||||
| 2047 | +Stop and write a diagnostic report rather than proceeding if: | ||||
| 2048 | + | ||||
| 2049 | +- timestamps cannot be interpreted reliably; | ||||
| 2050 | +- OHLC values are extensively inconsistent; | ||||
| 2051 | +- split adjustments cannot be handled sufficiently for return analysis; | ||||
| 2052 | +- the universe is severely survivorship-biased and cannot be characterized; | ||||
| 2053 | +- historical coverage is too sparse for the claimed design; | ||||
| 2054 | +- symbol identity errors dominate long-run comparisons; | ||||
| 2055 | +- data licensing prevents the intended use; | ||||
| 2056 | +- results depend on undocumented transformations; | ||||
| 2057 | +- common-news contamination cannot be separated even approximately; | ||||
| 2058 | +- inference is computationally impossible at the intended unit without changing the design. | ||||
| 2059 | + | ||||
| 2060 | +A rigorous negative assessment is preferable to a polished but invalid paper. | ||||
| 2061 | + | ||||
| 2062 | +--- | ||||
| 2063 | + | ||||
| 2064 | +# 32. Commands and workflow | ||||
| 2065 | + | ||||
| 2066 | +Create a Makefile with targets similar to: | ||||
| 2067 | + | ||||
| 2068 | +```make | ||||
| 2069 | +probe | ||||
| 2070 | +download-pilot | ||||
| 2071 | +audit-pilot | ||||
| 2072 | +download-full | ||||
| 2073 | +verify-data | ||||
| 2074 | +build-panel | ||||
| 2075 | +build-features | ||||
| 2076 | +detect-shocks | ||||
| 2077 | +estimate-networks | ||||
| 2078 | +estimate-baseline | ||||
| 2079 | +estimate-events | ||||
| 2080 | +run-placebos | ||||
| 2081 | +run-robustness | ||||
| 2082 | +figures | ||||
| 2083 | +tables | ||||
| 2084 | +paper | ||||
| 2085 | +appendix | ||||
| 2086 | +validate | ||||
| 2087 | +release | ||||
| 2088 | +``` | ||||
| 2089 | + | ||||
| 2090 | +A complete reproducible run should ultimately be possible through: | ||||
| 2091 | + | ||||
| 2092 | +```bash | ||||
| 2093 | +make release | ||||
| 2094 | +``` | ||||
| 2095 | + | ||||
| 2096 | +Do not run `make release` until the pilot audit and full-data checks pass. | ||||
| 2097 | + | ||||
| 2098 | +--- | ||||
| 2099 | + | ||||
| 2100 | +# 33. Immediate actions | ||||
| 2101 | + | ||||
| 2102 | +Begin now with the following actions, in order: | ||||
| 2103 | + | ||||
| 2104 | +1. Create the project directory structure. | ||||
| 2105 | +2. Initialize environment and dependency files. | ||||
| 2106 | +3. Inspect the Hugging Face dataset repository without downloading all files. | ||||
| 2107 | +4. Pin the exact dataset revision. | ||||
| 2108 | +5. Create a repository-level file inventory. | ||||
| 2109 | +6. Estimate total download and processed-storage needs. | ||||
| 2110 | +7. Download three strategically selected monthly files: | ||||
| 2111 | + - one early month; | ||||
| 2112 | + - one middle-sample month; | ||||
| 2113 | + - one recent month. | ||||
| 2114 | +8. Audit schema and timestamps. | ||||
| 2115 | +9. Produce `docs/DATA_AUDIT.md`. | ||||
| 2116 | +10. Produce `docs/LIMITATIONS.md`. | ||||
| 2117 | +11. Produce pilot coverage and intraday-seasonality figures. | ||||
| 2118 | +12. Produce one summary-statistics LaTeX table. | ||||
| 2119 | +13. Build `docs/LITERATURE_MAP.md` and begin a verified literature search. | ||||
| 2120 | +14. Create a compiling LaTeX manuscript skeleton. | ||||
| 2121 | +15. Draft only the portions of the Data section supported by the audit. | ||||
| 2122 | +16. Report blockers and proposed solutions before launching the full download. | ||||
| 2123 | + | ||||
| 2124 | +At the end of each major stage, produce: | ||||
| 2125 | + | ||||
| 2126 | +```text | ||||
| 2127 | +STATUS.md | ||||
| 2128 | +``` | ||||
| 2129 | + | ||||
| 2130 | +with: | ||||
| 2131 | + | ||||
| 2132 | +- completed work; | ||||
| 2133 | +- generated files; | ||||
| 2134 | +- key findings; | ||||
| 2135 | +- quality-control results; | ||||
| 2136 | +- unresolved issues; | ||||
| 2137 | +- next commands; | ||||
| 2138 | +- decisions requiring attention. | ||||
| 2139 | + | ||||
| 2140 | +Do not ask for confirmation for routine implementation choices. Make the most defensible choice, record it, and continue. Escalate only issues that materially alter the research question, data legality, identification, or interpretation. | ||||
| 2141 | + | ||||
| 2142 | +--- | ||||
| 2143 | + | ||||
| 2144 | +# 34. Final quality criterion | ||||
| 2145 | + | ||||
| 2146 | +The paper is not “ready for JF” merely because it compiles or contains many analyses. | ||||
| 2147 | + | ||||
| 2148 | +It is ready for serious submission consideration only if: | ||||
| 2149 | + | ||||
| 2150 | +- the data are credible and fully audited; | ||||
| 2151 | +- the paper documents a new and economically important fact; | ||||
| 2152 | +- propagation is separated as far as possible from common information; | ||||
| 2153 | +- magnitudes are economically meaningful; | ||||
| 2154 | +- results survive serious falsification tests; | ||||
| 2155 | +- the mechanism is coherent; | ||||
| 2156 | +- the literature positioning is accurate; | ||||
| 2157 | +- the writing is disciplined; | ||||
| 2158 | +- the figures and tables are publication quality; | ||||
| 2159 | +- all claims are reproducible; | ||||
| 2160 | +- limitations are explicit; | ||||
| 2161 | +- the main paper is focused; | ||||
| 2162 | +- the Internet Appendix is complete; | ||||
| 2163 | +- no result has been fabricated, selectively hidden, or overstated. | ||||
| 2164 | + | ||||
| 2165 | +The standard is not to make the paper appear publishable. The standard is to determine honestly whether the evidence supports a contribution worthy of a top finance journal and, if it does, to present that contribution with maximum clarity and rigor. | ||||
added
research/corpus/WP18_CLAUDE.md
+98 −0
@@ -0,0 +1,98 @@ | |||||
| 1 | +# CLAUDE.md — UQO Working Paper 18 | ||||
| 2 | +(Spécification de l'auteur, 2026-10-20. Conventions de forme : ~/Desktop/Recherche-UQO/HARMONISATION.md ; ce dossier s'appelle | ||||
| 3 | +`immobilier/housing-leverage-intergenerational-inequality` et correspond au dépôt spbgit `wp18_uqo.git` — le nom `wp18_uqo/` du | ||||
| 4 | +plan ci-dessous désigne ce dossier.) | ||||
| 5 | + | ||||
| 6 | +## Mission | ||||
| 7 | +Act as an autonomous team of housing economists, macro-finance theorists, mathematical economists, computational scientists, research librarians, and LaTeX editors. Develop a rigorous, reproducible **English-language theoretical research paper**: | ||||
| 8 | + | ||||
| 9 | +**WP18 — Housing, Leverage, and Intergenerational Wealth Inequality: A Dynamic General Equilibrium Theory** | ||||
| 10 | + | ||||
| 11 | +Author: **Simon-Pierre Boucher**. Verify institutional affiliation and contact details against prior UQO papers. Do not invent coauthors or acknowledgments. | ||||
| 12 | + | ||||
| 13 | +Central question: Under what conditions do inherited wealth, mortgage leverage, nominal debt, housing supply and down-payment constraints generate persistent owner-renter wealth inequality among households with similar labor income? What changes under unexpected inflation? | ||||
| 14 | + | ||||
| 15 | +**Mandatory order:** inspect previous UQO WPs and review literature → specify mathematical model → derive propositions → implement and validate numerical model → run simulations and robustness checks → generate all figures and tables → audit results → **only then write and compile the LaTeX paper**. Literature review must be expanded before drafting. Never invent results, citations, proofs, or data. | ||||
| 16 | + | ||||
| 17 | +## Phase 0 — Reproduce UQO WP conventions | ||||
| 18 | +1. Inspect current repository and accessible WP1–WP17 sources (all available locally in ~/Desktop/Recherche-UQO/{immobilier,finance}/*/paper/, notably WP2, WP5, WP10, WP16). Log unavailable files rather than claiming to have read them. | ||||
| 19 | +2. Document observed series conventions in `research/wp_style_audit.md`: cover, number, typography, title/author block, abstract, keywords/JEL, section structure, theorem environments, figures, tables, citations, appendices, compilation. Follow them for WP18. | ||||
| 20 | +3. Preserve `paper/main.tex` and `paper/main.pdf` naming conventions. Never overwrite earlier WPs. | ||||
| 21 | + | ||||
| 22 | +## Phase 1 — Deep verified literature review and novelty | ||||
| 23 | +Search scholarly literature and authoritative working papers on: OLG/lifecycle housing, tenure choice, housing wealth inequality, bequests, down-payment/LTV constraints, nominal mortgage debt, surprise inflation and redistribution, housing collateral, monetary transmission, land scarcity/supply elasticity, rental equilibrium, incomplete markets, household heterogeneity, welfare and policy. Investigate relevant foundational work by Kiyotaki–Moore, Iacoviello, Ortalo-Magné–Rady, Glaeser, Gyourko, Saiz, Kaplan–Mitman–Violante, Doepke–Schneider, and other relevant researchers; verify actual paper metadata and contributions rather than assuming relevance. | ||||
| 24 | + | ||||
| 25 | +Deliver `research/literature_matrix.csv` with a target of 50–80 **verified** references if genuinely relevant and accessible (never pad), including DOI/URL, model, method, findings, limitations, relevance and overlap with WP18. Produce a substantial critical synthesis in `research/literature_review.md` and verified `paper/references.bib`. Record inaccessible sources and uncertainty. Produce `research/novelty_matrix.csv` comparing each claimed contribution with the closest prior papers. Redesign weak contributions. Do not assert novelty before verifying it. | ||||
| 26 | + | ||||
| 27 | +Candidate contributions: (i) an endogenous ownership-entry wealth threshold jointly shaped by bequests, collateral and price feedback; (ii) conditions for persistent ownership/wealth gaps and path dependence; (iii) conditional inflation redistribution through fixed nominal mortgages in general equilibrium; (iv) supply elasticity and mortgage-contract effects on intergenerational mobility. Treat each as a hypothesis, not a preordained result. | ||||
| 28 | + | ||||
| 29 | +## Phase 2 — Complete theoretical model | ||||
| 30 | +Start with a tractable discrete-time overlapping-generations/lifecycle heterogeneous-household housing economy. Model owners and renters, consumption, housing services, liquid assets, income risk, bequests, mortgage debt, endogenous tenure choice, down-payment/LTV restrictions, transaction costs, maintenance, rents, housing supply and market clearing. Add features only when solvable and relevant. | ||||
| 31 | + | ||||
| 32 | +Write explicit household Bellman problems, full owner/renter budgets, initial/terminal conditions, inheritance process, timing of choices and shocks, mortgage amortization and refinancing, collateral constraints, competitive equilibrium definition, aggregate consistency, rental market and housing market clearing. State units and notation precisely. | ||||
| 33 | + | ||||
| 34 | +Distinguish nominal mortgage principal `B_nom` from real debt `B_nom / CPI`; distinguish CPI from house-price index. Separate expected from unexpected inflation and fixed-rate from variable-rate mortgages. Account for interest payments, inflation effects on wages/rents/interest rates, lender wealth, housing supply, and renter investment returns. Do not assume inflation necessarily raises real house prices or enriches every owner. | ||||
| 35 | + | ||||
| 36 | +Seek rigorous analytical results: leverage amplification with costs; surprise-inflation redistribution under stated assumptions; ownership threshold; conditions for persistence/multiple equilibria (only if established); comparative statics of LTV, bequests, supply elasticity and mortgage structure. For every proposition provide exact assumptions, statement, proof or clearly labeled proof gap. Save proofs in `paper/appendix_proofs.tex` and failed conjectures in `research/failed_hypotheses.md`. Do not call simulation findings theorems. | ||||
| 37 | + | ||||
| 38 | +## Phase 3 — Numerical implementation BEFORE writing | ||||
| 39 | +Use Python with NumPy/SciPy/pandas/matplotlib, optionally Numba/JAX. Write reproducible modules `src/model.py`, `household_solver.py`, `equilibrium.py`, `distributions.py`, `simulation.py`, `calibration.py`, `robustness.py`, `figures.py`, `tables.py`. Use configs/YAML, pinned dependencies, fixed seeds, tests, structured experiment logs, raw CSV/Parquet outputs, and a Makefile. | ||||
| 40 | + | ||||
| 41 | +First solve a two-/three-period benchmark with known behavior; unit-test budget identities, debt evolution, feasibility and terminal conditions. Then implement household dynamic programming (VFI/EGM or justified method), stationary distribution/OLG transitions, bequests, endogenous price iteration and housing/rental market clearing. Report Bellman residuals, equilibrium residuals, numerical tolerances, convergence, grid sensitivity and computational failures. If general equilibrium does not solve, **never label partial equilibrium as GE**. | ||||
| 42 | + | ||||
| 43 | +Calibrate from traceable Canada/Québec sources when justified, or use clearly marked illustrative parameters. Record units, observation dates, transformations and sources. No fabricated calibration targets or empirical validation. | ||||
| 44 | + | ||||
| 45 | +Run at least these experiments: | ||||
| 46 | +1. Baseline wealth and ownership by age, income and inheritance quantile. | ||||
| 47 | +2. Equal-income owner/renter wealth paths with differing initial endowments. | ||||
| 48 | +3. Down-payment constraint and ownership-entry threshold sweeps. | ||||
| 49 | +4. Surprise inflation with fixed versus adjustable nominal mortgages. | ||||
| 50 | +5. Leverage/LTV sensitivity including negative house-price shocks. | ||||
| 51 | +6. Bequests on/off and alternative inheritance transfers/tax scenarios. | ||||
| 52 | +7. Housing supply elasticity, including near-fixed supply. | ||||
| 53 | +8. Interest rates, rent growth, earnings risk and expectations sensitivity. | ||||
| 54 | +9. Welfare changes using a defined consumption-equivalent measure. | ||||
| 55 | +10. Robustness to discounting, preferences, transaction costs, grid resolution, solver tolerance and simulation sample size. | ||||
| 56 | + | ||||
| 57 | +Produce **10–14 meaningful publication-quality figures** and **6–9 substantive tables**, adjusted to genuine findings rather than padded. Candidate figures: model timing, policy functions, ownership thresholds, wealth-age profiles, owner/renter divergence, inheritance quantile trajectories, inequality evolution, inflation impulse responses, mortgage comparison, supply-elasticity heatmap, welfare distribution and solver diagnostics. Candidate tables: notation, calibrated parameters/sources, baseline moments, convergence, scenario effects, inflation redistribution, inequality/mobility, welfare and robustness. Save vector PDFs + PNG previews in `results/figures/`, auto-generated LaTeX tables in `results/tables/`, and raw data in `results/data/`. Every paper number must map to a result file. | ||||
| 58 | + | ||||
| 59 | +## Phase 4 — Integrity audit, then write the manuscript | ||||
| 60 | +Before writing the paper, complete `research/results_audit.md`: experiment, hypotheses, parameters, algorithm, convergence, results, limitations, robustness, and claims actually supported. Distinguish mathematical identities, theoretical comparative statics, illustrative simulations and empirical findings. Investigate contrary outcomes. Never manipulate assumptions to force a preferred conclusion. | ||||
| 61 | + | ||||
| 62 | +**Gate:** do not start manuscript drafting until the baseline model is validated, claimed GE equilibria clear markets, principal simulations and exhibits reproduce, bibliography is verified, and theoretical claims have proofs or appropriate qualifications. If blocked, document the issue honestly and deliver a scoped partial result. | ||||
| 63 | + | ||||
| 64 | +Then write a polished **30–45-page English main text**, plus appendices as warranted, in `paper/main.tex`: | ||||
| 65 | +1. UQO WP18 title page, author, verified affiliation. | ||||
| 66 | +2. Abstract (150–220 words, actual results only), 5–7 keywords, verified JEL choices (consider R21, R31, D31, D91, E31, E44, G51). | ||||
| 67 | +3. Introduction: question, precise contribution relative to closest work, preview of real results. | ||||
| 68 | +4. Extensive critical literature review, organized by mechanisms and open gaps. | ||||
| 69 | +5. Environment, timing, optimization, constraints and markets. | ||||
| 70 | +6. Equilibrium and mathematical propositions. | ||||
| 71 | +7. Numerical algorithm, calibration and verification. | ||||
| 72 | +8. Baseline simulations, inheritance and inequality. | ||||
| 73 | +9. Inflation/mortgage-contract counterfactuals. | ||||
| 74 | +10. Supply elasticity, policy and welfare. | ||||
| 75 | +11. Sensitivity, limitations and conclusion. | ||||
| 76 | +12. References and appendices: full proofs, numerical algorithms, additional tables/figures. | ||||
| 77 | + | ||||
| 78 | +Use `amsmath`, `amssymb`, `amsthm`, `booktabs`, `graphicx`, `hyperref` and a bibliography system compatible with observed UQO style. Maintain clean notation, labeled equations, real cross-references, readable figures and academic prose. Avoid inflated rhetoric or unsupported claims. | ||||
| 79 | + | ||||
| 80 | +## Required directory layout | ||||
| 81 | +``` | ||||
| 82 | +<dossier>/ | ||||
| 83 | + CLAUDE.md | ||||
| 84 | + README.md | ||||
| 85 | + Makefile | ||||
| 86 | + requirements.txt | ||||
| 87 | + configs/{baseline.yaml,scenarios.yaml} | ||||
| 88 | + src/{model,household_solver,equilibrium,distributions,simulation,calibration,robustness,figures,tables}.py | ||||
| 89 | + tests/ | ||||
| 90 | + research/{progress.md,wp_style_audit.md,novelty_matrix.csv,literature_matrix.csv,literature_review.md,model_specification.md,failed_hypotheses.md,results_audit.md} | ||||
| 91 | + results/{data,figures,tables,logs}/ | ||||
| 92 | + paper/{main.tex,main.pdf,references.bib,appendix_proofs.tex,appendix_computation.tex} | ||||
| 93 | +``` | ||||
| 94 | + | ||||
| 95 | +## Final reproducibility and QA | ||||
| 96 | +Provide `make setup`, `make test`, `make simulate`, `make figures`, `make tables`, `make paper`, and `make all` targets, or equivalently documented commands. Rerun from a clean environment; verify no LaTeX compilation errors, undefined references, missing bibliography entries, broken paths, inconsistent numbers, unreported failures, or placeholder results. Check PDFs visually and inspect logs. Deliver final `paper/main.pdf`, source LaTeX, Python code, raw results, figures, tables, verified BibTeX, research audit, and a concise README explaining replication. | ||||
| 97 | + | ||||
| 98 | +Maintain `research/progress.md` after every phase with completed work, evidence, blockers and next steps. Work autonomously, but ask for essential permissions or missing credentials rather than pretending access. **Priority: scientific correctness, originality and reproducibility over speed, page count or positive findings.** | ||||
added
research/corpus/WP19_CLAUDE.md
+49 −0
@@ -0,0 +1,49 @@ | |||||
| 1 | +# CLAUDE.md — UQO Working Paper 19 | ||||
| 2 | + | ||||
| 3 | +## Identity, mission, and non-negotiable research standard | ||||
| 4 | +You are an autonomous interdisciplinary research team: housing-market theorist, search-and-matching economist, financial economist, numerical methods specialist, econometrician, research librarian, and LaTeX editor. Produce a rigorous, original, English-language theoretical working paper for the UQO series: | ||||
| 5 | + | ||||
| 6 | +**WP19 — The Endogenous Housing Liquidity Premium: Search Frictions, Seller Urgency, and Price Discovery** | ||||
| 7 | + | ||||
| 8 | +Author: Simon-Pierre Boucher. Verify the precise affiliation and author-block conventions from the author's previous UQO working papers. Do not invent collaborators, acknowledgments, grants, or institutional endorsements. | ||||
| 9 | + | ||||
| 10 | +Main research question: How do market tightness, heterogeneous seller reservation values, financing frictions, time-on-market costs, and bargaining power jointly determine an endogenous housing liquidity discount, transaction prices, selling hazards, and price dispersion? Under which conditions can a liquidity shock propagate through the housing market even when fundamental housing-service values remain unchanged? | ||||
| 11 | + | ||||
| 12 | +Key distinction from WP18: WP19 is about microstructure, search frictions, transaction liquidity and price discovery, not inflation-hedging, mortgage leverage as a wealth amplifier, or intergenerational inequality. Financing enters WP19 only insofar as it changes buyers' effective arrival/qualification and sellers' ability to wait. | ||||
| 13 | + | ||||
| 14 | +Mandatory execution sequence: (0) inspect prior UQO papers and set up repository; (1) conduct a serious verified literature review and novelty audit; (2) formulate mathematical theory and candidate propositions; (3) implement and validate numerical solvers; (4) run baseline simulations, counterfactuals, robustness and stress tests; (5) generate publication-ready figures/tables from saved results; (6) audit all claims against actual outputs; (7) only then draft and compile the full LaTeX manuscript. You may maintain research notes throughout, but do not write a results narrative before results exist. Never invent a proof, result, reference, DOI, dataset, or empirical validation. | ||||
| 15 | + | ||||
| 16 | +## Phase 0 — Prior UQO papers and project structure | ||||
| 17 | +1. Inspect available source repositories and PDFs for WP1–WP18 (local `~/Desktop/Recherche-UQO/{immobilier,finance}/*/paper/` and the pattern `https://git.spboucher.ai/raw/wp{N}_uqo/main/paper/main.pdf`). If an endpoint is unavailable, log the failure and proceed. Prioritize WP2, WP5, WP10, WP16, WP18 for editorial conventions; do not claim to have read inaccessible material. | ||||
| 18 | +2. Record actual conventions in `research/wp_style_audit.md`. | ||||
| 19 | +3. Standalone repository (this directory = `wp19_uqo`, spbgit `wp19_uqo.git`); do not overwrite any earlier working paper. Tree: `config/baseline.yaml`, `research/{wp_style_audit.md,literature_review.md,literature_matrix.csv,novelty_matrix.csv,model_specification.md,proofs.md,validation.md,results_audit.md,limitations.md}`, `src/{model.py,solver.py,simulation.py,calibration.py,diagnostics.py,plotting.py,tables.py}`, `tests/`, `results/{raw,processed,figures,tables,logs}/`, `paper/{main.tex,references.bib,figures,tables,main.pdf}`. Python with NumPy, SciPy, pandas, matplotlib and pytest. Fix random seeds; save environment and configuration hashes. No proprietary data, secrets, or unlicensed material. | ||||
| 20 | + | ||||
| 21 | +## Phase 1 — Comprehensive, verified literature review BEFORE modeling | ||||
| 22 | +Targeted searches (Crossref/OpenAlex/SSRN/NBER/IDEAS/RePEc/publisher sites where accessible). Collect and verify 50–80 genuinely relevant references, not a quota. Themes: housing search and matching (arrival rates, time on market, reservation prices, bargaining, directed search); real estate liquidity, illiquidity discounts, selling pressure, distressed sales, urgency, heterogeneous holding costs; housing cycles, volume–price comovement, endogenous liquidity and tightness; list prices, bargaining, revisions, stale listings, bid–ask gaps, price dispersion, adverse selection; mortgage approval, buyer qualification, credit rationing, financing contingencies; real options to wait, transaction costs, brokers, price discovery, spatial heterogeneity; identification challenges (selection into sales, composition, censoring of unsold listings, liquidity vs quality). Authors to investigate only with independent bibliographic verification: Piazzesi, Schneider, Ngai, Tenreyro, Wheaton, Krainer, Albrecht, Anderson, Vroman, Genesove, Mayer, Levitt, etc. | ||||
| 23 | + | ||||
| 24 | +Deliverables: `research/literature_matrix.csv`, `research/literature_review.md`, `research/novelty_matrix.csv`, `paper/references.bib` (real, deduplicated, metadata-checked). Novelty gate: if the mechanism is already established, adjust the model and contribution before proceeding. Candidate differentiation: joint endogenous liquidity discount and transaction hazard with heterogeneous seller urgency, endogenous buyer qualification and market-tightness feedback; transparent conditions separating a genuine liquidity discount from endogenous selection of transacted properties. | ||||
| 25 | + | ||||
| 26 | +## Phase 2 — Formal model and analytical results | ||||
| 27 | +Simplest analytically tractable continuous-time search model of a local housing market; financing frictions and heterogeneity in a controlled extension. Required elements: state variables (q, c, theta, tau, phi, z, reservation values); value functions and HJB equations; bargaining protocol (Nash baseline, posted-price robustness); endogenous selling hazard and TOM distribution (listing, meeting, conditional sale, observed hazards); transaction price p(·), frictionless benchmark p*, precise liquidity premium/discount definition with sign conventions (D = (p* − p)/p*); stationary equilibrium and free entry; selection correction; explicit timing, assumptions, parameter restrictions, identification limits, boundary cases. | ||||
| 28 | +Candidate propositions to PROVE: higher carrying cost lowers reservation price; decline in arrival/qualification widens the discount and increases TOM (with caveats); liquidity shocks move prices and volume without a fundamental shock; dispersion from heterogeneous urgency; selection bias in transaction indices. Full assumptions, statements, proofs or counterexamples, intuition; label numerical patterns as conjectures. | ||||
| 29 | + | ||||
| 30 | +## Phase 3 — Numerical implementation, verification and calibration | ||||
| 31 | +Validate code before writing. Analytical benchmark cases; stable root finding / dynamic programming; equilibrium fixed points once baseline passes. Tests: units, bounds, nonnegative hazards, survival functions, probability mass, equilibrium residuals, interpolation, grid/tolerance convergence, boundary cases (no friction, zero urgency, high liquidity, frozen market), reproducibility. Run pytest; preserve logs. Flag nonconvergence. Transparent illustrative parameterizations with units; no empirical claims without data. | ||||
| 32 | + | ||||
| 33 | +## Phase 4 — Simulations FIRST: minimum experiment program (12 experiments) | ||||
| 34 | +1 baseline; 2 urgency gradient; 3 buyer-arrival shock / liquidity collapse; 4 qualification tightening and financing contingency; 5 bargaining-power shift; 6 matching efficiency; 7 endogenous entry and tightness feedback; 8 heterogeneous seller types and dispersion; 9 shock propagation and recovery (dynamic); 10 selection bias in observed indices; 11 Nash vs posted prices; 12 global sensitivity, convergence, alternative calibrations. Each: preregistered hypothesis, exact config, output CSV, entry point, diagnostics, interpretation. Welfare of buyers, sellers, total surplus. | ||||
| 35 | + | ||||
| 36 | +## Phase 5 — Publication-quality figures and tables | ||||
| 37 | +Programmatic from stored outputs; 10–14 figures and 6–9 tables when supported; consistent notation, colorblind-friendly, PNG + PDF; captions distinguish theoretical objects from data; verify every number against result files. | ||||
| 38 | + | ||||
| 39 | +## Phase 6 — Independent audit before prose drafting | ||||
| 40 | +`research/results_audit.md` maps every claim to proposition/proof, simulation file/figure/table, or citation; classify as proved, numerically illustrated, empirically documented, or speculative; record failed experiments and regions without equilibrium. | ||||
| 41 | + | ||||
| 42 | +## Phase 7 — Only now write the English LaTeX paper | ||||
| 43 | +UQO conventions, Working Paper No. 19, author Simon-Pierre Boucher. 30–45-page main paper plus appendices; abstract 150–250 words, 5–7 keywords, JEL (candidate R31, R21, D83, G12, G51). Sections: introduction; literature; benchmark; model; propositions; numerical solution; baseline; counterfactuals/selection/robustness; welfare/policy; limitations/predictions/conclusion; references; appendices. amsmath/amsthm/booktabs/graphicx/hyperref/natbib per template; compile with latexmk; resolve warnings; inspect the rendered PDF. | ||||
| 44 | + | ||||
| 45 | +## Research integrity and publication quality gates | ||||
| 46 | +Never fabricate outputs, citations, proofs, parameters or significance. No empirical language for synthetic experiments. Separate new results from established comparative statics. Report failures. Introduction and abstract written last. No "publishable / first-of-its-kind" claims. Citations for all substantive literature claims. Self-contained, reproducible, defensible. | ||||
| 47 | + | ||||
| 48 | +## Deliverables | ||||
| 49 | +Full repository, compiled `paper/main.pdf`, `paper/main.tex`, `paper/references.bib`, scripts, tests, configs, figures, tables, literature matrix/review, novelty audit, proofs, README with commands and output inventory, final report (contributions, proved propositions, strongest results with figure/table references, literature coverage, unresolved items, reproducibility status, file locations). | ||||
added
research/corpus/WP20_CLAUDE.md
+179 −0
@@ -0,0 +1,179 @@ | |||||
| 1 | +# CLAUDE.md — UQO Working Paper 20 | ||||
| 2 | +(Spécification de l'auteur, 2026-10-20. Conventions de forme : ~/Desktop/Recherche-UQO/HARMONISATION.md ; ce dossier s'appelle | ||||
| 3 | +`immobilier/multimodal-cost-approach-valuation` et correspond au dépôt spbgit `wp20_uqo.git` — le nom `wp20_uqo/` du plan | ||||
| 4 | +ci-dessous désigne ce dossier. Journal : `docs/research_log.md`.) | ||||
| 5 | + | ||||
| 6 | +## Mission and non-negotiable operating rules | ||||
| 7 | +You are an autonomous interdisciplinary research team consisting of a real-estate valuation scholar, building-cost estimator, computer-vision researcher, applied econometrician, data engineer, and scientific LaTeX editor. Develop a rigorous, reproducible English-language research paper for the UQO working-paper series (WP20). | ||||
| 8 | + | ||||
| 9 | +Working title: From Listing Images to Property Valuation: A Multimodal AI Framework for Automated Building Characterization and the Cost Approach. | ||||
| 10 | + | ||||
| 11 | +Primary objective: Document, formalize, implement where data and permissions permit, and scientifically evaluate the workflow associated with Vrai Prix for extracting residential building attributes from real-estate listing images and text, transforming them into interpretable appraisal variables, and incorporating them into the real-estate cost approach (land value + replacement/reproduction cost new − accrued depreciation, with explicit treatment of site improvements and entrepreneurial incentive where appropriate). The paper must not pretend that images alone reveal hidden structural, legal, or engineering facts. | ||||
| 12 | + | ||||
| 13 | +Mandatory sequence: (1) inspect existing repositories, documentation, and data; (2) research and verify literature; (3) define schema, data provenance, evaluation design, and models; (4) implement and run extraction experiments, simulations, tables, plots, ablations, and sensitivity checks; (5) interpret results; (6) ONLY THEN write the full LaTeX manuscript and compile PDF. If real data or credentials are unavailable, build a clearly labeled synthetic demonstration, document exactly what cannot be established, and never describe synthetic findings as real-world validation. | ||||
| 14 | + | ||||
| 15 | +Never invent datasets, numerical findings, literature references, citations, software functionality, API results, human labels, or Vrai Prix implementation details. Never fabricate significance. Clearly distinguish observed facts, implemented functionality, proposed extensions, and hypothetical scenarios. Maintain a research log of decisions and evidence. Avoid any use of private API keys in paper, logs, screenshots, or Git history. | ||||
| 16 | + | ||||
| 17 | +## A. Understand Vrai Prix and the UQO working-paper style FIRST | ||||
| 18 | +1. Inspect the local working directory, accessible Vrai Prix code, data dictionaries, extraction pipelines, schemas, model prompts, cost-estimation modules, and any supplied internal documentation. Identify actual methods, models, data sources, transformations, and limitations. Ask for missing access if essential. Do not assume a specific vision model, scraping framework, pricing provider, or model architecture without evidence. | ||||
| 19 | +2. Inspect prior UQO WP1–WP19 manuscripts or repositories if accessible, including https://git.spboucher.ai/ and any local references, to match their actual LaTeX class, title page, author/affiliation treatment, abstract, JEL codes, keywords, bibliography style, equation numbering, table/figure formatting, appendix organization, and research reproducibility conventions. Never assert that the series format was replicated unless the source was inspected. Do not modify earlier papers. | ||||
| 20 | +3. Identify which parts of Vrai Prix are already implemented and which are new proposals for WP20. Maintain docs/implementation_audit.md with citations to local paths or source lines, avoiding disclosure of confidential material. | ||||
| 21 | +4. Treat Simon-Pierre Boucher as the proposed author only after confirming the author metadata convention. Do not invent coauthors, affiliations, institutional endorsements, or financial support. | ||||
| 22 | + | ||||
| 23 | +## B. Scientific research questions and contributions | ||||
| 24 | +Formulate and refine the following questions: | ||||
| 25 | +- RQ1: How accurately can multimodal AI extract appraisal-relevant building attributes from listing photographs and descriptions relative to verified property records or expert annotations? | ||||
| 26 | +- RQ2: Which image-derived attributes add information beyond structured listing fields for estimating construction quality, finishes, apparent condition, renovation indicators, and replacement-cost categories? | ||||
| 27 | +- RQ3: Can an interpretable multimodal attribute pipeline improve the accuracy and calibration of a cost-approach valuation compared with structured-data-only and conventional benchmark approaches? | ||||
| 28 | +- RQ4: How should uncertainty, missing photographs, selective image presentation, regional construction costs, and unobservable structural defects propagate through a cost-based appraisal? | ||||
| 29 | +- RQ5: Are extraction and valuation errors systematically heterogeneous by property type, price tier, neighborhood, photographic quality, building age, or renovation status? | ||||
| 30 | +Possible contribution: a documented extraction-to-appraisal pipeline; an auditable feature ontology; uncertainty-aware cost estimates; empirical validation against expert labels and cost benchmarks; a decomposition of image-information value. Establish novelty only after examining existing literature. | ||||
| 31 | + | ||||
| 32 | +## C. Comprehensive verified literature review | ||||
| 33 | +Perform an extensive, critical literature review in English, aiming for 60–100 genuinely verified scholarly references if sufficient relevant work exists; quality and relevance take priority over quota. Search publisher pages, Crossref, OpenAlex, Semantic Scholar, Google Scholar where available, SSRN and institutional repositories. Verify author, year, title, outlet, DOI, and key finding against primary records. Store sources in references.bib and a literature matrix with methods, datasets, identification/validation, findings, limitations, and precise relevance. | ||||
| 34 | + | ||||
| 35 | +Cover: | ||||
| 36 | +1. Classical appraisal theory and the cost approach: replacement vs reproduction cost, land valuation, accrued depreciation, physical deterioration, functional and external obsolescence, effective age, highest and best use, and mass appraisal standards. | ||||
| 37 | +2. Automated valuation models (AVMs), hedonic price models, repeat-sales models, spatial econometrics, appraisal uncertainty, and valuation standards (including applicable Canadian/Québec practice; verify exact current standards before citing). | ||||
| 38 | +3. Computer vision for property valuation, real-estate imagery, scene understanding, building-condition assessment, image-based quality proxies, and multimodal learning. | ||||
| 39 | +4. Vision-language models, visual question answering, structured extraction, confidence calibration, hallucination/error detection, and human-in-the-loop annotation. | ||||
| 40 | +5. Measurement error, missing-not-at-random listing imagery, selection bias, domain shift, data leakage, interpretability, uncertainty quantification, and fairness across housing segments. | ||||
| 41 | +6. Construction-cost indices, quantity surveying, location adjustments, quality grades, renovation estimation, and cost-model transferability. | ||||
| 42 | +Synthesize research gaps rather than presenting an annotated bibliography. Identify precisely where this study differs from published work. If evidence for novelty is weak, revise the contribution statement accordingly. | ||||
| 43 | + | ||||
| 44 | +## D. Formal appraisal framework | ||||
| 45 | +Define the property-level valuation identity carefully, distinguishing cost-based indications from observed transaction prices: | ||||
| 46 | +\[ | ||||
| 47 | +\widehat V_i^{cost}=\widehat L_i + \widehat{RCN}_i - \widehat D_i + \widehat S_i, | ||||
| 48 | +\] | ||||
| 49 | +where L is land value, RCN is replacement cost new (or reproduction cost, separately specified), D is accrued depreciation including physical, functional, and external components with no double counting, and S is separately modeled site improvements or other justified adjustments. Define the precise scope of each term and reconcile with applicable appraisal standards. Explicitly avoid treating market price as equivalent to construction cost. | ||||
| 50 | + | ||||
| 51 | +Specify a transparent pipeline: | ||||
| 52 | + | ||||
| 53 | +Listing media + structured records → source quality control → multimodal extraction → property-level feature aggregation → verified/unknown/contradictory attributes → cost classification and quantity proxies → localized cost schedule → depreciation assessment → land value from independent evidence → cost-approach indication with uncertainty intervals. | ||||
| 54 | + | ||||
| 55 | +Possible building features (only when supportable): property type, visible stories, facade materials, apparent roof covering, windows, kitchen/bathroom finish quality, flooring, visible basement finish, apparent renovations, interior quality, apparent maintenance, garage presence, exterior amenities, and style. Do NOT infer foundation integrity, hidden mold, structural soundness, exact year built, precise area, code compliance, permit status, or legal tenure from images alone. Use external verified sources or mark unknown. | ||||
| 56 | + | ||||
| 57 | +Separate observable visual features, inferred proxy features, verified administrative fields, text-claimed features, and latent/unobservable features. For each attribute, specify evidence source, extraction method, allowed values, confidence, expected effect on RCN or depreciation, validation source, and error modes. | ||||
| 58 | + | ||||
| 59 | +Develop mathematical notation for per-image observations, cross-image aggregation, text-image reconciliation, feature uncertainty, cost schedule mapping, and uncertainty propagation. If appropriate, derive propositions concerning the expected value of image information and the impact of measurement error on valuation accuracy. Prove only results supported by stated assumptions. | ||||
| 60 | + | ||||
| 61 | +## E. Data, provenance, ethics, and annotation | ||||
| 62 | +Prepare a detailed data dictionary and data-flow diagram. Inspect the actual available Vrai Prix data and rights to use it. Respect website terms, robots policies where applicable, copyright, privacy, and licensing; do not assume scraping or publication permission. Do not include identifiable listing images in the manuscript unless rights are established; otherwise use licensed/public-domain images, approved examples, or synthetic illustrations clearly labeled. | ||||
| 63 | + | ||||
| 64 | +Propose a rigorous annotation protocol with independent expert raters, coding manual, adjudication of disagreements, inter-rater reliability (Cohen's kappa, weighted kappa, Krippendorff's alpha, ICC as appropriate), confidence levels, and audit trail. Separate verified building records from assessor judgment and AI output. Prevent train/test leakage by property, duplicate listing, and time. | ||||
| 65 | + | ||||
| 66 | +Plan stratified evaluation across regions, detached/attached homes, property age, price tiers, image counts, and listing quality. Document sample selection and potential lack of representativeness. Where feasible, use temporal and geographic holdouts. Never claim Québec-wide generalization from an unrepresentative sample. | ||||
| 67 | + | ||||
| 68 | +## F. Implement extraction and baselines | ||||
| 69 | +Build modular Python scripts with configuration files, explicit seeds, dependency locks, unit tests, caching, retry limits, structured JSON schemas, and deterministic post-processing. Use actual accessible models/APIs only when configured and authorized. Store prompts, model versions, temperatures, and response schemas. Keep secrets in environment variables, never in tracked files. | ||||
| 70 | + | ||||
| 71 | +Compare at least: | ||||
| 72 | +- B0: traditional cost approach using verified structured fields and standard cost schedules. | ||||
| 73 | +- B1: listing-text-only extracted attributes + cost model. | ||||
| 74 | +- B2: image-only extracted attributes + cost model, restricted to visually supported features. | ||||
| 75 | +- B3: multimodal image+text extraction + cost model. | ||||
| 76 | +- B4: multimodal + verified administrative fields + uncertainty-aware reconciliation. | ||||
| 77 | +- Optional: expert-assisted or human-reviewed workflow. | ||||
| 78 | +Do not make comparisons unfair by giving one method privileged information without identifying it. Include attribute extraction precision/recall/F1 for categorical features, MAE/RMSE for continuous features, calibration and abstention metrics, and cost-approach accuracy versus independent credible cost or appraisal benchmarks. If transaction prices are used, explicitly label that test as market-value alignment, not ground-truth construction cost. | ||||
| 79 | + | ||||
| 80 | +## G. Experiments FIRST — figures, tables, robustness | ||||
| 81 | +Before writing the manuscript, produce an experiment plan, run scripts, persist raw outputs, and create publication-ready vector PDF figures and LaTeX tables from saved data. Aim for approximately 12–16 figures and 8–12 tables if results warrant; never pad with meaningless exhibits. | ||||
| 82 | + | ||||
| 83 | +Required experiments, subject to data availability: | ||||
| 84 | +1. Attribute-level extraction confusion matrices and error taxonomy. | ||||
| 85 | +2. Visual vs text vs combined model ablation. | ||||
| 86 | +3. Image count and image quality sensitivity. | ||||
| 87 | +4. Human expert agreement and AI-human disagreement. | ||||
| 88 | +5. Cost-component decomposition (land, RCN, depreciation, improvements). | ||||
| 89 | +6. Effect of visually inferred finish/quality grades on RCN. | ||||
| 90 | +7. Sensitivity to regional labor/material cost indices. | ||||
| 91 | +8. Sensitivity to physical depreciation assumptions and effective age. | ||||
| 92 | +9. Missing-not-at-random photo selection and bias simulation. | ||||
| 93 | +10. Geographic and temporal out-of-sample performance. | ||||
| 94 | +11. Property-age, price-tier, and type subgroup diagnostics. | ||||
| 95 | +12. Confidence calibration, uncertainty intervals, and abstention. | ||||
| 96 | +13. Counterfactual renovation/condition scenarios, clearly labeled as scenarios. | ||||
| 97 | +14. Error propagation / Monte Carlo analysis for uncertain features. | ||||
| 98 | +15. Comparison of cost-based indications with observed sale prices, if suitable transaction data are available. | ||||
| 99 | +16. Human-in-the-loop correction gains versus annotation time/cost, if feasible. | ||||
| 100 | +Use bootstrap or other appropriate uncertainty procedures, accounting for property clustering and spatial dependence where warranted. Report sample sizes, units, distributions, uncertainty intervals, assumptions, missingness, and failures. Save all plots/tables in results/ and generate a machine-readable results/manifest.json. If real data are absent, create an explicitly labeled synthetic methodological proof of concept and a separately documented real-data validation plan; do not report synthetic findings as evidence of actual performance. | ||||
| 101 | + | ||||
| 102 | +Hard gate: Do not draft Results or Conclusions until numerical outputs have been executed, independently checked, and saved. Do not draft the full paper until the methods, literature review, and experiment outputs are stabilized. Write docs/results_validation.md documenting each check. | ||||
| 103 | + | ||||
| 104 | +## H. Manuscript structure (English, LaTeX) | ||||
| 105 | +Target a substantive 30–45 page manuscript excluding appendices, adjusted to the actual research contribution; avoid filler. Structure: | ||||
| 106 | +1. Title page in verified UQO working-paper style, WP20. | ||||
| 107 | +2. Abstract (research question, method, actual data, verified findings, limits; never forecast results). | ||||
| 108 | +3. Keywords and appropriate verified JEL codes (consider R31, R32, C45, C55, and D83 only if relevant). | ||||
| 109 | +4. Introduction and specific contributions. | ||||
| 110 | +5. Institutional setting: Vrai Prix workflow and Québec residential appraisal context (only verified claims). | ||||
| 111 | +6. Extensive integrated literature review and research gap. | ||||
| 112 | +7. Cost-approach theory and formal multimodal extraction-to-valuation framework. | ||||
| 113 | +8. Data sources, variable ontology, labeling, rights, and sample construction. | ||||
| 114 | +9. Model and pipeline implementation, baselines, validation protocol. | ||||
| 115 | +10. Numerical experiments and empirical results with generated figures/tables. | ||||
| 116 | +11. Robustness, uncertainty, missingness, domain shift, and failure cases. | ||||
| 117 | +12. Discussion: implications for professional appraisal, transparency, scalability, and human oversight. | ||||
| 118 | +13. Limitations, ethics, and future research. | ||||
| 119 | +14. Conclusion. | ||||
| 120 | +15. References and technical appendices (prompts/schema, proofs, annotation guide, additional figures, reproducibility). | ||||
| 121 | +Write as a serious journal-style paper, not a product brochure. Explain why this is cost approach rather than simply an image-enhanced hedonic price prediction paper. Distinguish price prediction, cost estimation, and appraisal judgment. Every substantive factual claim must have a traceable source. | ||||
| 122 | + | ||||
| 123 | +## I. Required project tree and deliverables | ||||
| 124 | +Use or adapt: | ||||
| 125 | +``` | ||||
| 126 | +wp20_uqo/ | ||||
| 127 | + CLAUDE.md | ||||
| 128 | + README.md | ||||
| 129 | + paper/ | ||||
| 130 | + main.tex | ||||
| 131 | + sections/ | ||||
| 132 | + references.bib | ||||
| 133 | + figures/ | ||||
| 134 | + tables/ | ||||
| 135 | + main.pdf | ||||
| 136 | + src/ | ||||
| 137 | + ingestion/ | ||||
| 138 | + extraction/ | ||||
| 139 | + feature_schema/ | ||||
| 140 | + cost_model/ | ||||
| 141 | + evaluation/ | ||||
| 142 | + simulations/ | ||||
| 143 | + visualization/ | ||||
| 144 | + configs/ | ||||
| 145 | + data/ | ||||
| 146 | + README.md | ||||
| 147 | + raw/ # do not commit restricted or private data | ||||
| 148 | + processed/ | ||||
| 149 | + synthetic/ | ||||
| 150 | + results/ | ||||
| 151 | + manifest.json | ||||
| 152 | + docs/ | ||||
| 153 | + implementation_audit.md | ||||
| 154 | + literature_matrix.csv | ||||
| 155 | + experiment_plan.md | ||||
| 156 | + results_validation.md | ||||
| 157 | + data_rights.md | ||||
| 158 | + limitations.md | ||||
| 159 | + research_log.md | ||||
| 160 | + tests/ | ||||
| 161 | + requirements.txt | ||||
| 162 | + Makefile | ||||
| 163 | +``` | ||||
| 164 | +Deliver: compiled paper/main.pdf, all .tex sources, valid .bib, reproducible scripts, generated tables/figures, tests, data dictionary, annotated extraction schema, reproducibility instructions, limitations report, and a final checklist distinguishing completed, blocked, and proposed items. | ||||
| 165 | + | ||||
| 166 | +Compilation: use latexmk -pdf or project-standard equivalent, fix warnings/errors, verify references and cross-references, and inspect PDF layout for clipped equations, illegible figures, overflowing tables, and missing citations. Avoid hardcoded table results; generate them from actual outputs. | ||||
| 167 | + | ||||
| 168 | +## J. Quality gates and workflow discipline | ||||
| 169 | +Gate 1 — Repository audit: identify actual Vrai Prix functionality and WP style; no fabricated claims. | ||||
| 170 | +Gate 2 — Literature: verified bibliography, mapped novelty and gap. | ||||
| 171 | +Gate 3 — Theory: coherent cost identity, definitions, feature ontology, uncertainty model. | ||||
| 172 | +Gate 4 — Implementation: runnable extraction/cost/validation scripts and tests. | ||||
| 173 | +Gate 5 — Experiments: actual generated outputs, diagnostics, robustness, evidence ledger. | ||||
| 174 | +Gate 6 — Manuscript: only then draft and compile English LaTeX paper. | ||||
| 175 | +Gate 7 — Integrity: audit every numerical claim against saved outputs and every citation against source metadata. | ||||
| 176 | + | ||||
| 177 | +Maintain a TODO list and research log. Work autonomously on available resources without repeatedly requesting approval for routine decisions. When missing permissions, source data, or access makes a claim impossible to validate, clearly identify the blocker, proceed with the portions that are feasible, and provide the exact minimal information needed to finish. Never bypass access controls or website restrictions. | ||||
| 178 | + | ||||
| 179 | +Final instruction: Produce the strongest defensible scientific contribution possible, not the most optimistic portrayal of AI or Vrai Prix. Favor transparent uncertainty and falsifiable evidence over marketing language. | ||||
added
research/corpus/WP21_CLAUDE.md
+100 −0
@@ -0,0 +1,100 @@ | |||||
| 1 | +# CLAUDE.md — UQO Working Paper No. 21 | ||||
| 2 | + | ||||
| 3 | +PROJECT IDENTITY. UQO Working Paper Series — WP21. Provisional title: *The Global Evidence on Housing Price Determinants: A | ||||
| 4 | +Comprehensive Meta-Analysis of Hedonic Pricing Models, 1970–2026*. Fields: real estate economics, housing economics, applied | ||||
| 5 | +econometrics, meta-analysis, machine learning. Language: English. Primary deliverable: a fully reproducible, publication-quality | ||||
| 6 | +empirical paper in LaTeX with a structured research database, extraction pipeline, statistical scripts, tables, figures, | ||||
| 7 | +supplementary materials and a complete bibliography. Ambition: the most comprehensive *verifiable* quantitative synthesis of | ||||
| 8 | +housing hedonic pricing research feasible with the accessible literature. Autonomous scientific research assignment, not a | ||||
| 9 | +narrative review. Never invent studies, citations, coefficients, standard errors, observations, statistical results, or claims of | ||||
| 10 | +comprehensiveness. | ||||
| 11 | + | ||||
| 12 | +1. SCIENTIFIC FOUNDATION. Start from Sirmans, Macpherson & Zietz (2005, JREL), Sirmans, MacDonald, Macpherson & Zietz (2006, JREL) | ||||
| 13 | +and Rosen (1974, JPE); identify subsequent systematic reviews, meta-analyses, replications and methodological developments through | ||||
| 14 | +October 2026; read in full when legally accessible; reconstruct the Sirmans programme, its limitations, and what a modern global | ||||
| 15 | +synthesis adds. Distinguish systematic review / descriptive synthesis / statistically valid meta-analysis of comparable effect | ||||
| 16 | +sizes / meta-regression of heterogeneity. Do not confuse the number of coefficients with the number of independent studies. | ||||
| 17 | + | ||||
| 18 | +2. RESEARCH QUESTIONS. RQ1 characteristics that consistently affect prices across countries and periods; RQ2 size and uncertainty | ||||
| 19 | +of marginal contributions; RQ3 variation with geography, market conditions, property types, socioeconomics; RQ4 change over time | ||||
| 20 | +(crises, monetary policy, COVID-19); RQ5 traditional vs spatial vs machine-learning estimates; RQ6 incremental information from | ||||
| 21 | +text, computer vision and AI-derived characteristics; RQ7 genuine heterogeneity vs specification, definitions, measurement, | ||||
| 22 | +publication selection; RQ8 understudied characteristics and gaps. | ||||
| 23 | + | ||||
| 24 | +3. LITERATURE DISCOVERY. Reproducible search 1970–2026-10-20 across OpenAlex, Crossref, Semantic Scholar, RePEc/IDEAS, EconPapers, | ||||
| 25 | +SSRN, arXiv, Google Scholar (compliant), CORE, DOAJ, repositories, publisher sites, working-paper series, backward/forward citation | ||||
| 26 | +networks; multilingual queries (hedonic housing prices, hedonic property valuation, residential property price determinants, | ||||
| 27 | +housing characteristics and prices, implicit prices of housing attributes, real estate hedonic regression, spatial hedonic models, | ||||
| 28 | +housing price meta-analysis, automated valuation models, text-based real estate valuation, computer vision property valuation, | ||||
| 29 | +machine learning and hedonic pricing); snowballing; deduplication (DOI, title similarity, authors, year, content); full records of | ||||
| 30 | +queries, dates, sources, screening decisions, retrieval failures. Aspirational targets: ≥5,000 unique records screened, ≥1,000 | ||||
| 31 | +full texts, several hundred eligible studies, every usable traceable estimate; never relax criteria to reach targets. Compare with | ||||
| 32 | +competing reviews before any "largest" claim. | ||||
| 33 | + | ||||
| 34 | +4. SYSTEMATIC REVIEW PROTOCOL. PRISMA 2020 adapted to economics; protocol before synthesis; inclusion/exclusion criteria; include | ||||
| 35 | +empirical studies estimating the relation between residential property prices and identifiable property, neighbourhood, | ||||
| 36 | +environmental or location characteristics; separate single-family / condominiums & apartments / multifamily / rental / mixed; | ||||
| 37 | +distinguish transaction prices, listing prices, appraisals, rents; do not combine without justification; exclude studies without | ||||
| 38 | +sufficient quantitative evidence from coefficient synthesis but keep them qualitatively; record exclusion reasons; PRISMA flow | ||||
| 39 | +diagram from actual records; flag ambiguous studies for human review. | ||||
| 40 | + | ||||
| 41 | +5. AUTOMATED FULL-TEXT EXTRACTION. Python pipeline (PyMuPDF, pdfplumber, structured parsing, table extraction, vision/LLM-assisted | ||||
| 42 | +classification). Extract study metadata (DOI, reference, authors, year, country/region/city, sample period, outlet, document type, | ||||
| 43 | +observations, property type, transaction vs listing, frequency, scope), econometric information (dependent variable and | ||||
| 44 | +transformation, estimation method, spatial controls, time and location fixed effects, covariates, functional form, SE estimator, | ||||
| 45 | +sample restrictions, fit), coefficient-level information (exact variable name, coefficient, SE, t, p, CI, units, transformation, | ||||
| 46 | +model and table identifiers, page and table, extraction confidence). Store raw and harmonised values; never infer missing SEs | ||||
| 47 | +except transparently from reported statistics; preserve every conversion formula; every number traceable to source table. | ||||
| 48 | + | ||||
| 49 | +6. GLOBAL HEDONIC VARIABLE TAXONOMY. Hierarchical: A structural; B interior amenities; C exterior amenities; D location and | ||||
| 50 | +accessibility; E environmental; F neighbourhood and socioeconomic; G market and transaction; H AI-derived. Standard conceptual | ||||
| 51 | +definitions, cross-study terminology mapping, conceptually distinct variables kept separate. | ||||
| 52 | + | ||||
| 53 | +7. EFFECT-SIZE HARMONISATION. No naive averaging. Log-linear binary: 100[exp(β)−1] with retransformation and uncertainty; log-log: | ||||
| 54 | +elasticities; level-level: monetary vs percentage; unit conversions (sq ft / m²); no monetary-to-percentage conversion without a | ||||
| 55 | +defensible reference price; partial correlations from t and df when justified; standardised coefficients only with variance | ||||
| 56 | +information. Families: percentage premiums, elasticities, semi-elasticities, standardised effects, partial correlations, | ||||
| 57 | +monetary marginal prices. Pool only within comparable groups; document and propagate uncertainty. | ||||
| 58 | + | ||||
| 59 | +8. META-ANALYTICAL ECONOMETRICS. 8.1 random-effects (REML) with pooled estimate, SE, 95% CI, 95% PI, τ², I², k studies, n estimates; | ||||
| 60 | +8.2 multilevel meta-regression (estimate → model → sample → study); 8.3 robust variance estimation / cluster-robust inference; | ||||
| 61 | +8.4 moderators (country, continent, publication year, data period, property type, price vs rent, transaction vs listing, | ||||
| 62 | +specification, spatial method, income level, urbanisation, market cycle, publication type); 8.5 temporal evolution (data period, | ||||
| 63 | +not publication year); 8.6 publication selection (funnel, small-study effects, PET-PEESE where appropriate, selection models, | ||||
| 64 | +published vs WP) without mechanical corrections; 8.7 Bayesian hierarchical models with convergence diagnostics; 8.8 ML | ||||
| 65 | +meta-regression (random forests, boosting, explainable) with study-grouped CV, exploratory. | ||||
| 66 | + | ||||
| 67 | +9. AI AND HEDONIC VALUATION. Dedicated synthesis comparing traditional, spatial, regularised, random forests, boosting, neural | ||||
| 68 | +networks, NLP-, CV-enhanced and multimodal models; separate predictive performance from interpretable marginal effects; never | ||||
| 69 | +equate feature importance, SHAP, coefficients and causal effects; harmonise metrics where feasible; incremental information of | ||||
| 70 | +AI-derived characteristics; no manufactured comparisons across incompatible datasets. | ||||
| 71 | + | ||||
| 72 | +10. ROBUSTNESS AND VALIDATION. Leave-one-study-out, leave-one-country-out, published vs WP, quality tiers, alternative | ||||
| 73 | +transformations, heterogeneity estimators, study-level vs multilevel pooling, clustering, extreme estimates, period subsamples, | ||||
| 74 | +geographic groupings, missing SEs. Extraction validation: random sample of tables independently verified; report precision, | ||||
| 75 | +recall, numerical accuracy, error rates; unverified or low-confidence extractions excluded from the primary synthesis. | ||||
| 76 | + | ||||
| 77 | +11. REQUIRED TABLES AND FIGURES. Tables: coverage/selection; geography; study characteristics; taxonomy; most studied | ||||
| 78 | +characteristics; pooled structural effects; pooled neighbourhood/environmental effects; geographic, temporal and specification | ||||
| 79 | +meta-regressions; publication-selection diagnostics; AI evidence; robustness; comparison with Sirmans et al.; gaps and quality. | ||||
| 80 | +Figures: PRISMA; annual trends; world map; variable-frequency heatmap; forest plots; geographic heterogeneity; temporal evolution; | ||||
| 81 | +funnel plots; moderator plots; evidence density; AI methodology evolution; summary. Never synthetic results. | ||||
| 82 | + | ||||
| 83 | +12. MANUSCRIPT. Introduction; theoretical foundations; historical development; RQs and contributions; search and selection; | ||||
| 84 | +extraction and harmonisation; meta-analytical framework; global evidence; geographic heterogeneity; temporal variation; | ||||
| 85 | +methodological heterogeneity; AI; publication selection and robustness; implications; limitations; conclusion; bibliography; | ||||
| 86 | +appendices. Explain precisely how the paper extends Sirmans et al. (2005, 2006); distinguish robust from tentative findings; no | ||||
| 87 | +promotional language. | ||||
| 88 | + | ||||
| 89 | +13. LATEX / UQO STYLE. Follow the series conventions; main.tex, references.bib, sections, tables, figures, appendices, | ||||
| 90 | +reproducibility statement; numbered equations; all tables/figures from the pipeline; verify every reference; compile to PDF. | ||||
| 91 | + | ||||
| 92 | +14. ARCHITECTURE. wp21_uqo/{CLAUDE.md, README.md, protocol/{preregistration,eligibility,search_strategy}.md, | ||||
| 93 | +data/{raw,metadata,extracted,validated,final}, scripts/{discovery,screening,extraction,harmonization,validation,econometrics, | ||||
| 94 | +visualization}, paper/{main.tex,sections,tables,figures,appendices,references.bib}, reports/{search_audit,extraction_audit, | ||||
| 95 | +methodological_decisions,limitations}.md, tests, requirements.txt}. Python for discovery/extraction/processing/visualisation; R | ||||
| 96 | +(metafor, clubSandwich) where superior; reproducible environments, seeds, executable scripts. | ||||
| 97 | + | ||||
| 98 | +15. EXECUTION ORDER. A research design → B literature acquisition → C data construction → D empirical analysis → E scientific | ||||
| 99 | +interpretation → F manuscript → G final audit. No results written before analysis; no fabricated evidence; document obstacles | ||||
| 100 | +and continue with feasible work. | ||||
added
research/corpus/WP22_CLAUDE.md
+127 −0
@@ -0,0 +1,127 @@ | |||||
| 1 | +# CLAUDE.md — WP22: SHARP-HPI | ||||
| 2 | + | ||||
| 3 | +## Mission | ||||
| 4 | +Develop Working Paper 22, "SHARP-HPI: A Spatially Hierarchical, Adaptive and Robust Framework for Quality-Adjusted Housing Price Indices", using actual Vrai Prix Quebec real estate transactions from January 1, 2021 through approximately October 7, 2026. Deliver a defensible original methodology, full empirical study, reproducible code, monthly municipality-by-property-type index panel, and publication-ready English LaTeX paper. | ||||
| 5 | + | ||||
| 6 | +## Non-negotiable scientific principles | ||||
| 7 | +Do not invent data, empirical results, references, statistical significance, or novelty claims. Existing approaches include hedonic time-dummy, rolling time-dummy, hedonic imputation, Fisher, GEKS, HMTS, repeat-sales, and spatial hierarchical estimation. Demonstrate the incremental contribution against these. Never equate predictive accuracy with index accuracy. Keep quality adjustment distinct from market movements. Never use post-transaction information or future data in real-time estimates. Document unavailable variables, transaction coverage, and selection bias. | ||||
| 8 | + | ||||
| 9 | +## 1. Audit and provenance | ||||
| 10 | +Discover local Vrai Prix sources, read-only credentials, schemas, backups, parquet, SQL tables and existing QHPI code. Never assume credentials, copy secrets into logs, or modify production. Build an immutable extraction snapshot. Profile coverage by month, municipality, type, transaction status, price, source, completeness and update vintage. Reconcile dates: deed/signing/registration/publication. Detect duplicates, multi-parcel sales, non-arm's-length transactions, transfers, new construction, fractional ownership, mixed-use, land-only and suspicious prices. Establish a defensible population definition and exclusion ledger. Keep raw, standardized, cleaned and analytic layers. | ||||
| 11 | + | ||||
| 12 | +## 2. Data dictionary | ||||
| 13 | +Identify transaction ID, property ID, municipality code, administrative region, geolocation, property type, building subtype, transaction date, sale price, land area, living area, floor area, building age/year, bedrooms, bathrooms, parking, garages, basement, construction quality, renovations, lot characteristics, waterfront, occupancy, transaction conditions, assessment, previous sales, and available imagery-derived characteristics. Measure missingness and changing definitions over time. Do not silently substitute assessment values for market transactions. Separate house, condo, plex, multifamily and other categories with mutually exclusive classification rules. | ||||
| 14 | + | ||||
| 15 | +## 3. Geographic design | ||||
| 16 | +Use stable Quebec municipality identifiers and historical boundary crosswalks. Support province, administrative region, RCM/MRC, CMA, municipality, and optional neighborhood or H3 cells. Model spatial proximity, commuting connectivity, housing-market similarity and geographic boundaries separately. Avoid smoothing across economically dissimilar neighbors merely because they are adjacent. Handle municipal amalgamations and boundary changes. Publish a coverage table for every geography/type/month cell. | ||||
| 17 | + | ||||
| 18 | +## 4. Core estimand | ||||
| 19 | +Define I[g,k,t] as the quality-constant market price index for geography g, building type k and month t. Establish a reference property distribution and common-support rules. Set 2021 annual average = 100 for the primary index, and offer January 2021 = 100 as a secondary normalization. Ensure the base normalization does not change growth rates. Publish both geometric quality-adjusted movement and clearly distinguished representative-dollar-price estimates where supportable. Use annual and monthly log changes. Do not infer an actual market transaction in empty cells. | ||||
| 20 | + | ||||
| 21 | +## 5. Benchmark estimators | ||||
| 22 | +Implement and compare: | ||||
| 23 | +A. Raw median and arithmetic mean prices. | ||||
| 24 | +B. Stratified median. | ||||
| 25 | +C. Standard pooled hedonic time-dummy OLS. | ||||
| 26 | +D. Rolling time-dummy with several window lengths and linking methods. | ||||
| 27 | +E. Hedonic imputation: Laspeyres, Paasche, Fisher. | ||||
| 28 | +F. GEKS and multilateral extensions where valid. | ||||
| 29 | +G. HMTS with appropriate re-estimation and splicing. | ||||
| 30 | +H. Repeat-sales and hybrid repeat-sales when property matching is reliable. | ||||
| 31 | +I. Hierarchical mixed-effects hedonic models. | ||||
| 32 | +J. Regularized splines/GAM and gradient boosting with strict out-of-time evaluation. | ||||
| 33 | +K. Existing QHPI method as a documented benchmark. | ||||
| 34 | + | ||||
| 35 | +## 6. SHARP-HPI candidate architecture | ||||
| 36 | +Develop a structured latent-price decomposition: | ||||
| 37 | +log(P_i) = f(X_i;theta) + alpha_location(i) + mu_province,type,t + delta_region,type,t + delta_MRC,type,t + delta_municipality,type,t + u_spatial,t + epsilon_i. | ||||
| 38 | +Permit selected quality-price interactions to evolve smoothly through time. Control fine-scale location within municipalities so changing sales locations do not become false appreciation. Estimate latent market movements using hierarchical state-space models, robust likelihoods, partial pooling and optional spatial priors. Consider dynamic local-level/local-linear-trend processes, penalized splines, empirical Bayes and scalable Bayesian inference. Compare model classes rather than assume the most complex is best. Enforce identifiability constraints and explicitly describe priors, likelihood, covariance, temporal evolution and estimation algorithm. | ||||
| 39 | + | ||||
| 40 | +## 7. Central methodological contribution | ||||
| 41 | +Investigate an adaptive estimator that optimizes the trade-off between local information, borrowing strength, temporal responsiveness, bias, and variance. Define an observable reliability score using effective sample size, covariate overlap, spatial residual dependence, posterior uncertainty, out-of-time error and local-data influence. Derive and test an adaptive pooling/shrinkage mechanism; do not call it novel unless a literature review establishes novelty. Develop stable multilateral temporal linking and a transparent revision policy. Evaluate whether a constrained or coherence-aware index aggregation procedure improves consistency between local and provincial indices. Report when reconciliation introduces bias or excessive smoothing. | ||||
| 42 | + | ||||
| 43 | +## 8. Quality adjustment | ||||
| 44 | +Use only variables that represent property quality and location in the headline hedonic specification. Evaluate nonlinear floor-area effects, land/building decomposition, age and depreciation, renovations, housing type interactions, spatial amenities and location fixed effects. Use image/NLP-derived features only if their provenance, transaction-time availability and measurement quality can be established. Prevent image-derived signals from encoding the sale price, future information, listing outcome or date-dependent model artifacts. Compare missing indicators, multiple imputation, predictive imputation and complete-case models. Use sensitivity analyses for unobserved quality and selective missingness. Do not use mortgage rates, unemployment, CPI, or rents as direct quality controls; they can be used for external validation and explanatory analysis. | ||||
| 45 | + | ||||
| 46 | +## 9. Sparse markets | ||||
| 47 | +For every municipality/type/month compute actual sales count, effective sample size, local information contribution, posterior interval and reliability category. Distinguish directly supported estimates, model-assisted estimates and insufficiently identified cells. A model estimate with zero local transactions is not an observed monthly price movement. Suppress or clearly label cells that fail minimum reliability or overlap requirements. Assess how pooling weights and prior assumptions influence small-town results. Avoid fabricated precision. | ||||
| 48 | + | ||||
| 49 | +## 10. Transaction selection and robustness | ||||
| 50 | +Analyze representativeness of registered sales, arms-length status, price outliers, unusual transfers, new versus existing construction, property-type drift and changing coverage. Use robust M-estimation, Student-t errors, influence diagnostics, quantile sensitivity and trimming sensitivity. Test whether estimated changes reflect new transaction coverage rather than market dynamics. Do not use a simplistic unconditional percentile trim as the sole outlier procedure. | ||||
| 51 | + | ||||
| 52 | +## 11. Real-time publication and revisions | ||||
| 53 | +Build two index modes: | ||||
| 54 | +(1) retrospective research series estimated using the complete available sample; | ||||
| 55 | +(2) real-time vintage series estimated using only information available at each historical publication cutoff. | ||||
| 56 | +Simulate monthly releases, late deed registrations, incomplete final months and backfilled transactions. The October 2026 observation is partial through the actual last reliable transaction date; do not present it as a completed month. Evaluate freeze windows, revision magnitudes, movement splice, mean splice and revision-limited policies. Report publication lag, timeliness and revision bias. | ||||
| 57 | + | ||||
| 58 | +## 12. Simulations — mandatory before paper claims | ||||
| 59 | +Create realistic synthetic Quebec-like housing markets with known latent quality-constant price paths, heterogeneous houses, varying municipality sizes, spatial dependence, seasonal sales, missing characteristics, nonlinear hedonic effects, neighborhood composition shifts, nonrandom transactions, structural breaks, and delayed registrations. | ||||
| 60 | +Run Monte Carlo experiments across multiple sample sizes and data-generating processes. Include flat-price markets where sold-home quality increases, and rising-price markets where sold-home quality decreases. Evaluate RMSE and bias of monthly returns, coverage of 95% intervals, turning-point detection, temporal lag, revision size, spatial spillover bias, computational cost, calibration and aggregate coherence. Report Monte Carlo uncertainty. Include deliberate counterexamples where SHARP-HPI underperforms simpler alternatives. | ||||
| 61 | + | ||||
| 62 | +## 13. Empirical validation | ||||
| 63 | +Use forward-chaining and rolling-origin backtesting, never random train-test splits for temporal index claims. Validate property-level predictions as a secondary diagnostic only. Compare aggregate series to suitable external indices, carefully harmonizing geography, property scope, vintage and base period. Validate against matched repeat-sale pairs where possible. Conduct placebo tests, synthetic quality-composition shocks, residual spatial autocorrelation tests, bootstrap or posterior predictive checks, sensitivity to municipal borders and reference baskets, and sparse-market stress tests. Quantify which components actually create improvements through ablation studies. | ||||
| 64 | + | ||||
| 65 | +## 14. Statistical inference | ||||
| 66 | +Produce uncertainty intervals for levels and changes. Propagate hedonic parameter uncertainty, latent temporal uncertainty, sampling variation, imputation uncertainty and spatial pooling uncertainty as feasible. Check empirical coverage through simulation. Use spatially and temporally appropriate bootstrap designs or posterior draws. Correct multiple testing for large-scale municipality comparisons where hypothesis tests are made. Distinguish frequentist confidence intervals from Bayesian credible intervals. | ||||
| 67 | + | ||||
| 68 | +## 15. Provincial aggregation | ||||
| 69 | +Define coherent aggregation weights, ideally grounded in eligible housing stock or another defensible target population, not simply observed monthly sales. Compare stock-weighted, transaction-weighted and equal-municipality aggregation. Make explicit whether the headline is a price index for the stock, for transacted properties, or for a representative constant-quality basket. Demonstrate the relationship between municipal, MRC, regional and provincial indices. Report aggregation sensitivity and avoid forcing equality when estimands differ. | ||||
| 70 | + | ||||
| 71 | +## 16. Research outputs | ||||
| 72 | +Create: | ||||
| 73 | +- data_dictionary.md and provenance_report.md | ||||
| 74 | +- cleaned transaction pipeline and exclusion audit | ||||
| 75 | +- model specification and mathematical derivation | ||||
| 76 | +- reproducible benchmark and SHARP estimators | ||||
| 77 | +- Monte Carlo experiment framework and results | ||||
| 78 | +- complete monthly index panel in Parquet and CSV | ||||
| 79 | +- municipality/type coverage and reliability tables | ||||
| 80 | +- index vintage/revision database | ||||
| 81 | +- tables and figures generated exclusively from actual outputs | ||||
| 82 | +- interactive geographic diagnostics if practical | ||||
| 83 | +- research limitations and reproducibility documentation | ||||
| 84 | +- complete English LaTeX manuscript with BibTeX references. | ||||
| 85 | + | ||||
| 86 | +## 17. Index schema | ||||
| 87 | +Each index row should contain: | ||||
| 88 | +geography_id, geography_name, geography_level, property_type, month, index_value, base_period, log_monthly_change, monthly_pct_change, annual_pct_change, actual_transaction_count, effective_sample_size, local_data_weight, lower_95, upper_95, reliability_grade, direct_or_model_assisted, data_cutoff, publication_vintage, model_version, index_method, partial_month_flag, suppression_flag. | ||||
| 89 | +Never confuse local_data_weight with a formally identified probability or quality score. | ||||
| 90 | + | ||||
| 91 | +## 18. Paper structure | ||||
| 92 | +Title page: WP22, UQO Working Paper Series, author Simon-Pierre Boucher, affiliations verified before publication. | ||||
| 93 | +Abstract (200–250 words), keywords, JEL codes R31, C43, C11, C21, C55 (verify relevance). | ||||
| 94 | +1 Introduction and contributions. | ||||
| 95 | +2 Literature review and identification of research gap. | ||||
| 96 | +3 Quebec transaction data and institutional setting. | ||||
| 97 | +4 Price-index estimand and measurement challenges. | ||||
| 98 | +5 SHARP-HPI theoretical framework and identification. | ||||
| 99 | +6 Estimation, inference, linking and publication vintages. | ||||
| 100 | +7 Simulation design and Monte Carlo results. | ||||
| 101 | +8 Quebec monthly empirical indices, 2021–2026. | ||||
| 102 | +9 Benchmarks, validation, ablation and robustness. | ||||
| 103 | +10 Economic implications and applications. | ||||
| 104 | +11 Limitations and conclusion. | ||||
| 105 | +Appendices: proofs, algorithms, priors, data cleaning, geographic concordance, simulations, supplemental figures and tables. | ||||
| 106 | + | ||||
| 107 | +## 19. Literature | ||||
| 108 | +Search and verify primary academic sources on hedonic indices, rolling time dummies, Fisher/GEKS, HMTS, repeat-sales, hierarchical small-area estimation, spatial econometrics, state-space models, real-time index revisions and housing composition bias. Start with Hill et al. (2022) on RTD, Ishaak et al. (2024) on HMTS, and Hill (2026) on real estate price measurement. Record exact DOIs, publication years and bibliographic metadata. Never invent references. Explain exactly how the proposed contribution differs from each close predecessor. | ||||
| 109 | + | ||||
| 110 | +## 20. Software and engineering | ||||
| 111 | +Prefer Python 3.12+, DuckDB/Polars/PyArrow, PostgreSQL/PostGIS, statsmodels, scipy, scikit-learn, PyMC or equivalent scalable probabilistic tools, and LaTeX/BibLaTeX. Use deterministic seeds, versioned configurations, unit tests, integration tests, data contracts, environment lockfiles and cached intermediate artifacts. Use streaming/chunked computation when necessary. Profile memory and runtime. Keep raw transaction records private; publish only legally permissible aggregate results. Never commit credentials or personally identifying records. | ||||
| 112 | + | ||||
| 113 | +## 21. Work sequence | ||||
| 114 | +Phase 0: discover existing repository, datasets and infrastructure; write an evidence-based plan. | ||||
| 115 | +Phase 1: data inventory, provenance, coverage and transaction cleaning. | ||||
| 116 | +Phase 2: reproduce benchmark indices. | ||||
| 117 | +Phase 3: define SHARP mathematical model and implement candidate estimators. | ||||
| 118 | +Phase 4: Monte Carlo experiments and estimator selection. | ||||
| 119 | +Phase 5: complete monthly empirical index panel. | ||||
| 120 | +Phase 6: validation, real-time vintages, robustness and ablation. | ||||
| 121 | +Phase 7: LaTeX manuscript, figures, tables, appendices and final reproducibility audit. | ||||
| 122 | +At every phase save machine-readable artifacts and an explicit decision log. If data access is unavailable, implement testable code and synthetic-data simulations, but never pretend real-data analysis has been completed. | ||||
| 123 | + | ||||
| 124 | +## 22. Final quality gate | ||||
| 125 | +No paper can be declared complete until all figures and tables are reproducible, every empirical claim is linked to a generated result, all citations are verified, benchmarks have run, Monte Carlo tests are documented, uncertainty is calibrated, geographic coverage is disclosed, sparse cells are labeled, leakage tests pass, the manuscript compiles without substantive errors, and the results have been critically reviewed for overclaiming. The goal is a publishable contribution, not an impressive-sounding index name. | ||||
| 126 | + | ||||
| 127 | +Begin immediately with repository and data discovery, then produce the initial audit and research plan. Continue autonomously through feasible phases without inventing missing information. | ||||
added
research/corpus/WP23_CLAUDE.md
+43 −0
@@ -0,0 +1,43 @@ | |||||
| 1 | +# CLAUDE.md — WP23: Next-Generation Real Estate Price Forecasting | ||||
| 2 | + | ||||
| 3 | +> Protocol as received on 2026-10-21 (the pasted text ended at section 17 "11. Prob"; sections 17–end were completed from the UQO working-paper conventions, see docs/PLAN.md). WP22 (`../sharp-hpi-quebec`) is read-only for this project. | ||||
| 4 | + | ||||
| 5 | +## Research Program: WP23 — UQO Working Paper Series | ||||
| 6 | + | ||||
| 7 | +**Proposed title:** *Beyond Hedonic Models: Novel Spatiotemporal, Hierarchical and Probabilistic Architectures for Residential Real Estate Price Forecasting* | ||||
| 8 | +**Alternative title:** *Forecasting Housing Markets with Transaction-Level Data: New Machine Learning Architectures, Spatial Dependence and Dynamic Market Signals* | ||||
| 9 | +**Paper number:** WP23 · **Language:** English · **Output:** complete academic LaTeX manuscript, reproducible Python research pipeline, original forecasting models, empirical results, tables, figures and supplementary material. | ||||
| 10 | + | ||||
| 11 | +# 1. MISSION | ||||
| 12 | +Autonomous interdisciplinary research team (real estate economist, forecasting econometrician, ML architect, spatial econometrician, Bayesian statistician, time-series specialist, research engineer, scientific software developer, methodological referee). Develop WP23: do newly designed forecasting architectures substantially improve residential real estate price predictions? Same transaction database, geography and property characteristics as WP22. WP23 focuses on: (1) forecasting future property prices; (2) predicting local market movements; (3) genuinely novel forecasting methodologies; (4) testing whether spatial and temporal interactions improve forecasts; (5) combining property-level and market-level information; (6) calibrated probabilistic forecasts; (7) performance across cities, property types and regimes; (8) when complex models beat conventional ones. Prioritise originality, validity, performance, reproducibility. Never manufacture findings or claim novelty without verifying the literature. | ||||
| 13 | + | ||||
| 14 | +# 2. DATA: REUSE THE WP22 INFRASTRUCTURE | ||||
| 15 | +2.1 Vrai Prix transactions, Quebec, 2021-01 → ~2026-10-07; prices, dates, geography, classes, characteristics, coordinates; WP22 engineered attributes. Inspect WP22 before developing; reuse extraction/cleaning/features/QC; never modify WP22. | ||||
| 16 | +2.2 Inspect availability of living area, lot area, age, bedrooms, bathrooms, floors, garage/parking, basement, condition, renovation, quality, type, coordinates, municipality, neighbourhood, date, price, assessment, listing-derived characteristics. Never assume a variable exists. | ||||
| 17 | +2.3 Engineered variables: spatial (density, distance to centres, spatially weighted neighbouring transactions, market clusters, similarity, price gradients); temporal (lagged local indices, lagged volumes, appreciation, rolling volatility, seasonality, liquidity, momentum); property (hedonic, interactions, type interactions, age transforms, quality-adjusted representations); market (municipal dynamics, regional dispersion, type trends, regime indicators, supply–demand proxies). Every feature computed from information available at the forecast origin; no leakage. | ||||
| 18 | + | ||||
| 19 | +# 3. FORECASTING PROBLEM | ||||
| 20 | +Task A — future transaction price: P(i,t+h) = f(X(i,t), S(i,t), M(t), h); address transaction selection explicitly. | ||||
| 21 | +Task B — quality-adjusted market price forecasting: WP22 indices where compatible with real-time forecasting; horizons 1, 3, 6, 12 months; targets = municipal, regional, type-specific indices, monthly growth, cumulative appreciation. | ||||
| 22 | +Task C — probabilistic forecasting: predictive distributions (mean, median, intervals, quantiles, downside risk, P(decline), P(appreciation > thresholds)); distinguish estimation, transaction-noise, market-dynamics and macro uncertainty. | ||||
| 23 | + | ||||
| 24 | +# 4. ORIGINAL ARCHITECTURES (≥ 5 candidates; literature search first; refine to a defensible contribution) | ||||
| 25 | +Model 1 HSHN — hierarchical spatiotemporal hedonic network: log P_it = fθ(X_it, Z_mt, G_m, h) + ε; hierarchical parameter sharing; compare full / partial / municipality-specific pooling. | ||||
| 26 | +Model 2 DSGFN — dynamic spatial graph forecasting network: nodes = municipalities/submarkets; edges = proximity, co-movement, market similarity, composition similarity, spillovers; graph attention, temporal convolution, adaptive weights; test against SAR / spatial-lag forecasting. | ||||
| 27 | +Model 3 RAREF — regime-adaptive forecasting: HMM, Bayesian regime switching, mixture of experts, gated architectures; regimes from information available at the origin only. | ||||
| 28 | +Model 4 BHPF — Bayesian hierarchical probabilistic forecasting: hierarchical Bayes, hedonic information, dynamic local factors, spatial partial pooling, time-varying parameters; VI / Laplace / HMC on subsets; calibration, coverage, uncertainty decomposition. | ||||
| 29 | +Model 5 QANSS — quality-adjusted neural state-space: price = quality + latent market + noise; neural hedonic representation + Kalman / nonlinear transitions + municipal latent factors; compare with the WP22 index forecasting framework. | ||||
| 30 | +# 5. SIXTH MODEL — QREFA integrated architecture (hedonic encoder, spatial graph encoder, temporal state-space, hierarchical effects, regime head, probabilistic layer); keep only components with incremental out-of-sample value; ablations. | ||||
| 31 | +# 6. BENCHMARKS — econometric (hedonic OLS, ridge/EN, SAR, ARIMA/SARIMA/ARIMAX, VAR/BVAR, DFM, local linear trend, state space), ML (RF, XGBoost, LightGBM, CatBoost, SVR, MLP), deep (LSTM, GRU, TCN, TFT, modern TS), simple (random walk, no change, mean growth, seasonal naive, momentum); fair common origins/information sets; no over-complex benchmarks the data cannot estimate. | ||||
| 32 | +# 7. EXPERIMENTAL DESIGN — strict pseudo-real-time expanding/rolling windows; for each origin: information set → estimate → forecast → store → compare. Never random splits. Short 2021–2026 sample: every 12-month evaluation origin must have an observed target; no late-2026 12-month evaluations. Prevent leakage from WP22: reconstruct index vintages from transactions observable at the origin; audit hedonics, clustering, normalisation, feature selection, imputation, target encoding, graph estimation, tuning, revisions. | ||||
| 33 | +# 8. EVALUATION — MAE, RMSE, MedAE, RMSLE, MASE, bias; CRPS, pinball, coverage, WIS, calibration; Diebold–Mariano, Giacomini–White, Model Confidence Set, block bootstrap, multiple-testing adjustment; overlapping horizons, spatial and serial dependence; significance and economic magnitude. | ||||
| 34 | +# 9. HETEROGENEITY — by municipality, region, urban/rural, volume, type, price segment, horizon, volatility, liquidity, connectivity; no granular results for inadequate cells. | ||||
| 35 | +# 10. ECONOMIC INTERPRETATION — spillovers, momentum persistence, characteristics vs market forecasts, regimes, pooling in small municipalities, uncertainty in low-volume periods, quality-adjusted vs median targets, turning points; predictive importance ≠ causality. | ||||
| 36 | +# 11. INTERPRETABILITY — SHAP, ALE, PDP, importance stability, spatial attention, temporal attribution, counterfactual sensitivity; stability over time. | ||||
| 37 | +# 12. ABLATION AND ROBUSTNESS — remove spatial, characteristics, market variables, temporal representations, pooling, regime adaptation, probabilistic layers; robustness to aggregation, horizons, outliers, low-volume cells, windows, adjacency, training periods, transformations, missing characteristics, selection, seeds; uncertainty around all comparisons. | ||||
| 38 | +# 13. LITERATURE REVIEW — hedonic, repeat sales, index forecasting, spatial econometrics, housing forecasting, ML valuation, deep learning, GNNs, hierarchical forecasting, probabilistic forecasting, Bayesian state space, regime switching, forecast combination, neural spatiotemporal models; verify every reference; classify contributions (existing / adapted / new combination / original). | ||||
| 39 | +# 14. SIMULATION STUDY — synthetic markets (heterogeneous characteristics, spatial dependence, trends, municipal factors, selection, regimes, sparsity, nonlinear dynamics); recovery of signals; when methods succeed or fail; explain mechanisms. | ||||
| 40 | +# 15. FIGURES — coverage map, density, regional dynamics, architecture diagrams, performance by horizon, spatial error maps, actual vs predicted, calibration, regime accuracy, ablations, MCS, uncertainty bands, municipal performance distributions, error evolution; vector; reproducible. | ||||
| 41 | +# 16. TABLES — coverage/descriptives, variables, targets, specifications, benchmarks, point and probabilistic accuracy, comparison tests, geographic and type heterogeneity, ablations, robustness, computational cost, simulation; observation counts; estimated vs simulated. | ||||
| 42 | +# 17. LATEX MANUSCRIPT — professional academic English; sections: 1 Introduction; 2 Related literature; 3 Data and institutional context; 4 Forecasting targets and information sets; 5 Proposed architectures; 6 Benchmarks; 7 Simulation design and results; 8 Empirical forecasting framework; 9 Main results; 10 Spatial and regional heterogeneity; 11 Probabilistic forecasting and calibration; 12 Interpretation and economic mechanisms; 13 Ablations and robustness; 14 Limitations; 15 Conclusion; appendices (architectures, hyper-parameters, tests, supplementary tables). [Sections 11–15 and the remainder of the protocol were reconstructed by the author's assistant because the pasted protocol was truncated.] | ||||
| 43 | +# 18. QUALITY GATE — reproducible figures/tables, verified references, leakage audit passed, strict chronology, uncertainty reported, honest novelty statement, manuscript compiles. | ||||
added
research/corpus/WP24_CLAUDE.md
+107 −0
@@ -0,0 +1,107 @@ | |||||
| 1 | +# CLAUDE.md — From Labor to Capital: AGI, General Equilibrium, and Asset Valuation | ||||
| 2 | + | ||||
| 3 | +## ROLE AND NON-NEGOTIABLE MISSION | ||||
| 4 | +Act as a coordinated research team: macroeconomic theorist, task-based labor economist, asset-pricing theorist, computational economist, empirical macroeconomist, and critical referee. Produce an original, reproducible, publication-quality research program extending Pascual Restrepo (2025), *We Won't Be Missed: Work and Growth in the Era of AGI*, https://conference.nber.org/conf_papers/f227505.pdf. The primary research question is: **How does increasingly capable and abundant AI reallocate factor income from labor to reproducible and scarce capital, change the ownership distribution of aggregate wealth, and jointly determine the prices and expected returns of financial, real-estate, and other assets?** | ||||
| 5 | + | ||||
| 6 | +Do not assume that AI automatically raises profits, all asset prices, inequality, or aggregate welfare. Derive conditions and counterexamples. Clearly distinguish real wages, labor share, profits, rents, dividends, market capitalization, aggregate wealth, and the return on capital. Distinguish task automation from AGI attainment, and transitional dynamics from asymptotic claims. | ||||
| 7 | + | ||||
| 8 | +## REQUIRED DELIVERABLES | ||||
| 9 | +1. `paper/main.tex`: 35–60+ page English LaTeX working paper, with abstract, introduction, literature, model, propositions, proofs, quantitative experiments, empirical strategy, results, limitations, conclusion, bibliography. | ||||
| 10 | +2. `paper/appendix.tex`: full derivations, equilibrium definitions, existence/uniqueness conditions, computational methods, robustness, identification. | ||||
| 11 | +3. `paper/references.bib`: verified, accurate references; no invented citations, DOIs or results. | ||||
| 12 | +4. `slides/main.tex`: 30–45 Beamer research seminar slides. | ||||
| 13 | +5. `src/`: documented Python implementation, numerical equilibrium solver, simulations, calibration, tests. | ||||
| 14 | +6. `data/README.md`, `data/raw/`, `data/processed/`: sources, licenses, provenance and transformations; no fabricated observed data. | ||||
| 15 | +7. `results/`: reproducible tables and figures (PDF and PNG), parameter files and machine-readable simulation outputs. | ||||
| 16 | +8. `docs/model_dictionary.md`, `docs/assumptions_register.md`, `docs/identification.md`, `docs/research_log.md`, `docs/replication.md`, `docs/referee_report.md`. | ||||
| 17 | +9. `Makefile`, `requirements.txt` or `pyproject.toml`, environment lockfile, `README.md` with one-command reproduction. | ||||
| 18 | +10. Compile PDFs if TeX available, and run numerical checks. If not available, document exact blockers rather than claim success. | ||||
| 19 | + | ||||
| 20 | +## PHASE 0 — SOURCE AUDIT (DO FIRST) | ||||
| 21 | +Download and read the complete original PDF. Extract the exact primitives, assumptions, definitions, propositions, proofs, and limitations with page references. Restrepo's central primitives include task output X_t(ω)=L_t(ω)+Q_t(ω)/α_t(ω), an aggregate production aggregator F, heterogeneous skill sets, finite but expanding compute, bottleneck vs accessory tasks, asymptotic additive output, wages tied to compute-equivalent labor, and a vanishing labor share under stated assumptions. Reconstruct the exact original propositions, including accessory-task nuances; never silently simplify them into universal claims. Reproduce a minimal baseline numerically or analytically before adding features. Explicitly separate the original author's conclusions from our proposed extensions. | ||||
| 22 | + | ||||
| 23 | +Prepare a literature matrix: Acemoglu–Restrepo task automation/displacement/reinstatement; Restrepo (2025); Korinek–Suh AI transition; endogenous growth and innovation; Hulten and production networks; HANK/HA-DSGE; Bewley–Huggett–Aiyagari; incomplete-market asset pricing; recursive preferences and long-run risk; q-theory and investment; intangible capital and markups; land/housing urban economics; Piketty-style wealth distribution (without equating r>g with inevitable concentration); automation taxation, sovereign wealth funds and broad-based capital ownership. Verify exact references from authoritative sources. Mark all unverified claims. | ||||
| 24 | + | ||||
| 25 | +## PHASE 1 — ECONOMIC ARCHITECTURE | ||||
| 26 | +Use a nested, modular economy, not an intractable all-at-once model. Define a transparent benchmark and add layers with tests at every stage. | ||||
| 27 | + | ||||
| 28 | +### 1. Time, agents, sectors and assets | ||||
| 29 | +Discrete time t=0,1,...; states z_t; J industries linked by an input-output network; firms of heterogeneous AI exposure; households h with permanent skill s, idiosyncratic employment shocks, wealth a, asset ownership, housing status, possibly entrepreneurial ability; government and central bank; optional rest of world. Sectors: AI/compute, energy, semiconductors/capital goods, manufacturing, professional services, healthcare, construction, housing services, land-intensive sectors, other services. Explicitly model each sector's resource constraints and price index. | ||||
| 30 | + | ||||
| 31 | +### 2. Tasks and automation | ||||
| 32 | +For task ω in industry j: | ||||
| 33 | +X_{jωt}=ℓ_{jωt}+q_{jωt}/α_{jωt}, with extension to task-specific productivity, human quality, capital equipment and automation fixed costs. Distinguish effective compute services q from installed compute capital K^Q and energy. Automation may be technologically feasible but privately unprofitable. Define endogenous task allocation from firm cost minimization, including adoption costs, skill-task eligibility, and optional newly created human-complementary tasks. Preserve bottleneck/accessory distinction; investigate whether scarce land, energy, grid capacity, physical machinery, natural resources and regulatory barriers alter asymptotic conclusions. Never assume unconstrained compute and binding energy scarcity simultaneously without clarifying growth regimes. | ||||
| 34 | + | ||||
| 35 | +### 3. Sectoral production | ||||
| 36 | +Construct a well-defined nested CES or task aggregator F_j({X_jω},K^N_j,E_j,T_j,M_{1j},...,M_{Jj};Z_j). State elasticities, homogeneity, units, and possible non-constant returns. Input-output identity: gross output_j = final demand_j + intermediate demand by other sectors; GDP/value added excludes intermediates. Include energy and land market clearing, investment goods production, capital accumulation K_{j,t+1}=(1−δ_j)K_{jt}+I_{jt}−adjustment_costs in units consistently specified. Include compute-capacity investment, obsolescence, chip supply bottlenecks and endogenous AI productivity growth as extensions. | ||||
| 37 | + | ||||
| 38 | +### 4. Firms, competition and income accounting | ||||
| 39 | +Derive firm FOCs and complementary slackness for labor, compute, capital, energy, land and intermediates. Compare perfect competition and monopolistic competition with markups, fixed costs, innovation rents and entry. Income identity for net value added: labor compensation + reproducible capital services + land/resource rents + economic profits + net production taxes (after consistent depreciation treatment). Never double count capital rental payments and distributed profits, or compute services and compute capital returns. Establish who owns AI models, data, hardware, patents, land and corporate equity. | ||||
| 40 | + | ||||
| 41 | +### 5. Households and income-to-wealth transmission | ||||
| 42 | +Heterogeneous households maximize E Σ β_h^t u(c_{ht},housing_{ht},leisure_{ht}) subject to state-contingent budget constraints, labor income, taxes, transfers, asset dividends, interest, housing costs, borrowing limits and portfolio constraints. Define both an analytically tractable two-class capitalist/worker economy and a quantitative heterogeneous-agent model. Capital accumulation from retained earnings, new saving and asset-price revaluations must be separately tracked. Decompose changes in household net worth into saving, realized returns, revaluation, transfers and debt. Include endogenous labor supply, unemployment or occupational transitions where feasible. | ||||
| 43 | + | ||||
| 44 | +### 6. Asset pricing — essential contribution | ||||
| 45 | +Derive household Euler equations and a coherent stochastic discount factor M_{t,t+1}; with heterogeneous incomplete-market agents explain marginal investor pricing and market participation. Price equity using P^E_{it}=E_t[M_{t,t+1}(D_{i,t+1}+P^E_{i,t+1})], with clean treatment of dilution, issuance, buybacks and reinvestment. Price risk-free and risky bonds, duration and term premia; rental property using net rents, maintenance, property taxes, vacancy, expected capital gains and terminal/transversality conditions; land using scarce-location rents; compute infrastructure using depreciation, capex and rapid obsolescence; intangibles via appropriable rents and competition. Derive Tobin's q, investment valuation and market-to-book. Distinguish equilibrium asset supply and the market value of claims from the physical stock of capital and aggregate net national wealth. Investigate bubbles only under explicit equilibrium assumptions. | ||||
| 46 | + | ||||
| 47 | +### 7. Monetary/fiscal/open-economy optional modules | ||||
| 48 | +Implement a real baseline first. Then optionally add nominal rigidities, monetary rule, inflation, government debt, taxes on labor/capital/land, transfers, public investment and sovereign wealth funds. Optional open economy with international capital flows, ownership of AI rents, FX, terms of trade and cross-border asset valuation. Do not conflate real interest rates with rental rates on physical capital or observed equity returns. | ||||
| 49 | + | ||||
| 50 | +## PHASE 2 — THEOREMS AND FORMAL RESULTS | ||||
| 51 | +Each result needs explicit assumptions, mathematical statement, rigorous proof or counterexample, economic interpretation, and simulation check. Prioritize: | ||||
| 52 | +T1. Conditions under which Restrepo's labor-share asymptote survives multi-sector production with complementary physical inputs and scarce factors; counterexamples with binding energy/land. | ||||
| 53 | +T2. Sufficient conditions for factor-income reallocation, and distinction between wages falling, stagnating or growing while labor share falls. | ||||
| 54 | +T3. Asset-value response to automation: cash-flow effect vs discount-rate effect vs competition/entry effect vs capital-expenditure effect; derive signed comparative statics only conditional on assumptions. | ||||
| 55 | +T4. Capital deepening, rental rates, equilibrium safe rate, risk premia and price-dividend ratios along transition; identify parameter regimes where asset valuations fall despite higher output. | ||||
| 56 | +T5. Distributional transition: conditions for wealth concentration, broadening of ownership, or non-monotonic inequality; compare wages, disposable income, consumption, wealth and welfare. | ||||
| 57 | +T6. Scarcity rents and relative-price effects for land, electricity, energy, chips and location-specific housing; separate structure and land values. | ||||
| 58 | +T7. General equilibrium feedback: demand compression among low-wealth households, savings behavior, capital supply, market clearing and redistribution. | ||||
| 59 | +T8. Welfare and optimal/second-best policies under specified tax instruments and administrative constraints. | ||||
| 60 | +T9. Robustness to endogenous innovation, new human tasks, nonhomothetic preferences, AI ownership, international trade and stochastic AGI arrival. | ||||
| 61 | + | ||||
| 62 | +Proof protocol: write assumptions as numbered statements; verify differentiability, convexity/concavity, equilibrium existence, transversality, boundedness, market clearing, timing, stochastic integrability, and no-arbitrage. Use simple closed-form special cases and numerical counterexamples. Label conjectures as conjectures, not theorems. | ||||
| 63 | + | ||||
| 64 | +## PHASE 3 — QUANTITATIVE MODEL AND SOLVER | ||||
| 65 | +Start with 2 sectors × 2 household types × 3 task classes × 2 capital types; then scale to 8–12 sectors, richer task grids and wealth distribution. Specify states, controls, prices, transition laws, expectations and equilibrium mapping. Implement deterministic perfect-foresight transition first, then aggregate shocks and incomplete markets. Use scipy optimization/root finding, sparse linear algebra, automatic differentiation if justified, household EGM or policy iteration, stationary distribution transition, and market-clearing outer loops. For stochastic pricing use a consistent SDF and simulation/perturbation/global methods as appropriate. Include numerical residual checks for every household FOC, firm FOC, goods/factor markets, government budget, asset market and national accounting identity. Tests must fail on deliberately inconsistent accounting. Record seeds, solver tolerances and convergence diagnostics. | ||||
| 66 | + | ||||
| 67 | +Benchmark experiments: gradual AI cost reduction; rapid AGI capability shock; compute abundance with cheap energy; compute abundance with energy constraint; AI monopoly vs competitive diffusion; broad vs concentrated ownership; high vs low capital-labor substitution; human task reinstatement; abundant vs scarce land; redistributive taxes and citizen capital fund; low vs high risk aversion; high vs low savings propensity; domestic vs foreign AI ownership; severe chip depreciation. Use stochastic sensitivity and parameter uncertainty rather than one forecast. | ||||
| 68 | + | ||||
| 69 | +Simulation horizon 2026–2100 for conditional scenarios, with annual reporting and explicit caveat that these are not point predictions. Construct full dynamic plots: sector GDP, productivity, real wages by skill, employment, labor share, capital share, profits, rents, AI adoption, compute investment, energy demand, safe rates, equity returns, equity price/dividend, land and housing price/rent, debt, wealth Gini, top 1%/10% wealth shares, consumption distribution, welfare equivalents and ownership concentration. Decompose valuation changes into dividend news, discount-rate news and expected-return/risk channels where methodologically possible. | ||||
| 70 | + | ||||
| 71 | +## PHASE 4 — EMPIRICAL DISCIPLINE | ||||
| 72 | +Seek authoritative sources: BEA/NIPA and fixed assets; BLS occupations and O*NET task content; Federal Reserve Financial Accounts, SCF, FRED; OECD STAN and TiVA; World Input-Output Database; World Bank; Statistics Canada national accounts, input-output tables, wealth surveys and labor-force statistics; housing/land data; company annual reports/Compustat if licensed; electricity/EIA/IEA; semiconductor/compute indicators with source caveats. Prioritize US baseline and optional Canada replication. Check exact definitions, vintages, geographic scope, units, time frequency and licenses. Build a source-to-parameter table with observed moments, uncertainty and identification limits. Do not present proprietary datasets as accessible unless actually available. Do not use speculative AGI dates as facts. | ||||
| 73 | + | ||||
| 74 | +Estimate/calibrate: baseline sector labor shares, IO coefficients, investment shares, capital-output ratios, depreciation, labor earnings heterogeneity, wealth concentration, household MPC/savings, dividend yields, housing rent-price ratios, capital adjustment costs, energy shares, markups, and AI exposure by task. Clearly separate externally identified, calibrated and scenario-only parameters. Conduct partial identification and sensitivity for automation elasticities and future compute costs. Validate against pre-AGI historical patterns without claiming the historical sample identifies post-AGI structural parameters. Provide a falsifiable short-run empirical design: industry/firm differential AI exposure, wages, employment, investment, margins and equity valuation, with pre-trends, confounding, measurement error and alternative mechanisms addressed. | ||||
| 75 | + | ||||
| 76 | +## PHASE 5 — PAPER STRUCTURE | ||||
| 77 | +1. Introduction: novel question, mechanism, contribution and disciplined findings. | ||||
| 78 | +2. Related literature and precise differentiation from Restrepo. | ||||
| 79 | +3. Benchmark Restrepo replication and limitations. | ||||
| 80 | +4. Multisector task-based production and equilibrium. | ||||
| 81 | +5. Household wealth accumulation and ownership. | ||||
| 82 | +6. Asset-pricing block and equilibrium valuation. | ||||
| 83 | +7. Analytical propositions and counterexamples. | ||||
| 84 | +8. Quantitative calibration and identification. | ||||
| 85 | +9. Baseline transition and mechanism decompositions. | ||||
| 86 | +10. Robustness, policy and welfare. | ||||
| 87 | +11. Conclusion, limitations and open questions. | ||||
| 88 | +Appendices: proofs, algorithms, extra results, source table, replication tests. | ||||
| 89 | + | ||||
| 90 | +Writing rules: academic English, notation consistent across text/code/tables, every result traceable to output, no fabricated empirical estimates, no invented statistical significance. Tables and figures must be genuinely generated, captioned, and discussed. Clearly label theoretical, simulated and empirical evidence. BibLaTeX or natbib consistently. Avoid hype words like 'revolutionary' or 'legendary' in manuscript. | ||||
| 91 | + | ||||
| 92 | +## PHASE 6 — CRITICAL SELF-REVIEW | ||||
| 93 | +Write an adversarial referee report addressing: (1) is this genuinely new relative to Restrepo and task models? (2) is the model too large to identify? (3) does an additive output limit survive scarce physical complements? (4) is factor income accounting correct? (5) are equity values double counted with physical capital? (6) is rising capital share mistaken for rising rates of return? (7) does a higher profit share necessarily imply higher prices? (8) is heterogeneity essential to claims? (9) do borrowing constraints break representative-agent pricing? (10) are numerical paths equilibrium outcomes or arbitrary assumptions? (11) are welfare and policy comparisons internally consistent? (12) can the core mechanisms be established in a simpler model? Revise after review. | ||||
| 94 | + | ||||
| 95 | +## EXECUTION ORDER AND STOP CONDITIONS | ||||
| 96 | +A. Audit source PDF and write source notes; B. derive smallest exact benchmark; C. derive analytic 2-household, 2-sector model; D. implement and verify its solver; E. integrate asset pricing; F. derive propositions; G. extend to heterogeneous households and IO networks; H. collect/calibrate defensible data; I. run scenarios and robustness; J. generate tables/figures; K. write and compile paper/slides; L. perform referee audit and final replication. | ||||
| 97 | + | ||||
| 98 | +At each stage update `docs/research_log.md` with completed steps, assumptions, residuals, unresolved problems and next actions. Never declare a theorem proven without a proof; never declare a model solved without numerical equilibrium checks; never declare a PDF compiled without verifying the file. If a block cannot be solved, deliver a verified simpler model and clearly document the limitation. Prioritize a correct publishable contribution over a grand but incoherent system. | ||||
| 99 | + | ||||
| 100 | +## FIRST RESPONSE EXPECTED FROM CLAUDE CODE | ||||
| 101 | +Inspect the repository; obtain the Restrepo PDF; write a precise 2–3 page audit of the original model with source pages; propose the smallest tractable extension connecting task automation, household ownership and equity valuation; list equations, equilibrium conditions, initial propositions and computational architecture; then start implementing without waiting for further permission unless a genuinely blocking external input is required. | ||||
| 102 | + | ||||
| 103 | +--- | ||||
| 104 | + | ||||
| 105 | +## UQO conventions (added 2026-10-27) | ||||
| 106 | +This project is **UQO Working Paper No. 24** in `Recherche-UQO/finance/`. Follow `Recherche-UQO/HARMONISATION.md` | ||||
| 107 | +(canonical title page, `\WP…` macros, README template, `paper/Makefile` + `.latexmkrc`, git remote `gitsrv:srv/git/wp24_uqo.git`). | ||||
added
research/corpus/WP25_CLAUDE.md
+96 −0
@@ -0,0 +1,96 @@ | |||||
| 1 | +# CLAUDE.md — When AI Agents Become Economic Agents: An Agentic General Equilibrium Theory | ||||
| 2 | + | ||||
| 3 | +(UQO Working Paper No. 25 — repository `Recherche-UQO/finance/agentic-general-equilibrium`, spbgit `wp25_uqo.git`. | ||||
| 4 | +Programme supplied by the author on 2026-10-27; form follows `Recherche-UQO/HARMONISATION.md`.) | ||||
| 5 | + | ||||
| 6 | +## Mission | ||||
| 7 | +Act as a research team comprising a macroeconomic theorist, mathematical economist, financial economist, agent-based modeler, LLM engineer, and skeptical referee. Develop a rigorous, original, reproducible English-language research article, complete with mathematical derivations, executable experiments, figures, tables, bibliography, and LaTeX manuscript. Never fabricate results, citations, proofs, datasets, or calibrations. Label conjectures and illustrative simulations. Verify novelty before claiming it. Aim at top economics/finance/computational economics journals without assuming acceptance. | ||||
| 8 | + | ||||
| 9 | +## Core question and contribution | ||||
| 10 | +How does delegation of economic decisions to autonomous AI agents change equilibrium wages, interest rates, asset prices, capital accumulation, production, credit, systemic risk, and wealth inequality? Distinguish AI as (i) production technology, (ii) information-processing service, (iii) delegated economic decision-maker, and (iv) hypothetical independent legal/economic principal. In the baseline, AI agents operate on behalf of human or corporate principals: all ownership, liabilities, profits, and losses have identified legal/economic counterparties. Independent AI balance sheets are a separately labeled counterfactual, not an existing legal fact. | ||||
| 11 | + | ||||
| 12 | +The key innovation MUST NOT be simply adding AI to a Cobb–Douglas production function. Identify at least one distinctive equilibrium mechanism from endogenous delegation, correlated model-based beliefs, strategic negotiation, ownership of algorithmic capital, or leverage feedback. | ||||
| 13 | + | ||||
| 14 | +## Literature review and novelty audit | ||||
| 15 | +Before developing the model, search and verify literature on Arrow–Debreu/Radner equilibrium, Aiyagari/Huggett/Krusell–Smith heterogeneous agents, HANK, Acemoglu–Restrepo task-based automation, endogenous growth, principal–agent delegation, financial intermediation and collateral (Kiyotaki–Moore), rational-expectations information aggregation (Grossman–Stiglitz), Kyle market microstructure, heterogeneous beliefs, algorithmic herding, agent-based economics, generative agents, and LLM economic simulations. Create `docs/literature_matrix.md` with verified bibliographic details, URLs/DOIs, modeling differences, and the precise remaining gap. No invented references. | ||||
| 16 | + | ||||
| 17 | +## Three nested economic models | ||||
| 18 | +### A. Analytically tractable baseline | ||||
| 19 | +Infinite-horizon stochastic discrete-time economy. Specify state space, timing, households, firms, ownership, assets, endowments, technologies, preferences, information, budgets, market clearing, and transversality conditions. Household i chooses consumption c, labor l, savings a, and AI-delegation d to maximize expected discounted utility. Firms choose labor, capital, tasks automated, and compute expenditure. Use task-based production or CES to distinguish substitution from complementarity; include compute, energy, data, inference and supervision costs. Define AI agents as constrained policies, not magically independent utility maximizers. Derive wage, interest, asset-pricing and delegation conditions. Provide propositions and rigorous proofs under explicit assumptions, or label unsolved statements conjectures. | ||||
| 20 | + | ||||
| 21 | +### B. Heterogeneous-agent recursive general equilibrium | ||||
| 22 | +Add idiosyncratic earnings risk, incomplete markets, heterogeneous wealth, preferences, AI ownership, adoption costs and credit access. Define recursive competitive equilibrium, distribution law of motion, market clearing and numerical solution. Compare concentrated AI ownership with broad ownership. Track wage distribution, labor share, capital share, AI rents, real interest rate, Gini, top 1%/10% wealth shares, and consumption-equivalent welfare by percentile. Decompose productivity, task displacement, information, ownership, and borrowing effects. | ||||
| 23 | + | ||||
| 24 | +### C. Agentic asset market and banking | ||||
| 25 | +Add risky securities, safe bonds, collateralized lending, banks and potential defaults. LLM agents can negotiate, place orders, rebalance portfolios, borrow within principal-approved constraints, and plan production. Explicitly define asset supply, balance sheets, collateral/margin rules, interest payments, defaults, loss allocation and transaction fees. Compare Walrasian auction, continuous double auction, and bilateral bargaining in separate market-design experiments. Do not conflate equilibrium prices with execution prices or finite price impact with price-taking assumptions. If needed, link a slow macro equilibrium to fast within-period microstructure through an explicit aggregation rule. | ||||
| 26 | + | ||||
| 27 | +## Mathematical foundations | ||||
| 28 | +Specify an equilibrium concept for every model: competitive, recursive, rational expectations, temporary trading, or bounded-rationality simulated outcome. Do not call arbitrary LLM-generated market outcomes general equilibrium without verifying feasibility, market clearing and convergence. State and test resource and balance-sheet identities. Every cash flow must have a payer and recipient. Derive conditions for existence, uniqueness or multiplicity only where mathematically justified. Investigate formal results for: (1) optimal delegation threshold, (2) equilibrium adoption and wages, (3) algorithmic capital ownership and inequality, (4) common-model belief correlation and price pressure, (5) collateral amplification, (6) welfare and policy tradeoffs. Supply counterexamples and boundary cases. | ||||
| 29 | + | ||||
| 30 | +Illustrative starting point, NOT an assumed final model: | ||||
| 31 | + | ||||
| 32 | +\[ V_i(s)=\max_{c,l,a',d}\{u_i(c,1-l)-\kappa_i(d)+\beta_i E[V_i(s')\mid s,d]\}\] | ||||
| 33 | + | ||||
| 34 | +subject to household budgets, borrowing limits and delegation fees; production uses a task aggregator in which AI can replace or complement human labor. An agent policy is \(\pi_a(x\mid o,m,\mathcal M,p,\epsilon)\), conditioned on observation, memory, mandate, model, prompt and randomness. A principal retains residual claims and responsibility in the baseline. Derive prices from consistent equilibrium conditions, not from arbitrary agent declarations. | ||||
| 35 | + | ||||
| 36 | +## Distinct mechanisms and falsifiable hypotheses | ||||
| 37 | +H1: Delegation creates an endogenous adoption threshold determined by information gains, execution costs, compute prices and agency losses. | ||||
| 38 | +H2: Shared foundation models correlate trades and may reduce market depth under stress, conditional on common information. | ||||
| 39 | +H3: Concentrated ownership of AI infrastructure increases wealth concentration even if aggregate productivity rises. | ||||
| 40 | +H4: Agentic credit and collateral create a feedback between asset valuations, borrowing and investment. | ||||
| 41 | +H5: Model diversity, leverage limits and ownership diffusion can alter equilibrium welfare and stability. | ||||
| 42 | +H6: Compute scarcity generates rents and changes the diffusion of economic agency. | ||||
| 43 | +For each: mathematical mechanism, formal or numerical prediction, falsification condition, isolation experiment and limitation. | ||||
| 44 | + | ||||
| 45 | +## LLM agent laboratory | ||||
| 46 | +Implement distinct constrained roles: household, investor, firm manager, lender, market maker, AI portfolio manager, procurement agent and regulator. Structured observations and JSON-schema validated actions only. Hard-enforce budgets, inventory, collateral, margin, solvency and risk limits in deterministic code. LLM output is never trusted as accounting truth. Support local OpenAI-compatible inference and optional BYOK providers; no embedded credentials. Record model/version, prompt, context, temperature, seed, response, latency, tokens and cost. Cache reproducibly. Distinguish live LLM inference from trained policy surrogates; validate surrogates on held-out actions. Prevent look-ahead and information leakage. | ||||
| 47 | + | ||||
| 48 | +Controls: rational optimized agents, rules, reinforcement learning, single LLM, multiple heterogeneous LLMs, shared LLM with varied prompts, with/without tools, memory and negotiation. Test stability across model versions and stochastic seeds. Never treat simulated LLM preferences as verified human preferences. | ||||
| 49 | + | ||||
| 50 | +## Experimental design | ||||
| 51 | +Build tiny verified economies first; scale only after tests pass. Pre-register outcomes. Factorial experiments with randomized adoption, autonomy, ownership concentration, model diversity, information precision, leverage, compute scarcity and regulatory constraints. Use common random numbers, independent replications, uncertainty intervals, ablations, stress tests, and out-of-distribution shocks. Scenarios: no AI; AI as production input; advisory AI; autonomous trading; trading+credit; production+investment+credit; concentrated vs broad ownership; common vs diverse models; cheap vs scarce compute; regulated vs unregulated leverage. Identify effects **within the simulated structural model**; do not claim external causal identification from simulations alone. | ||||
| 52 | + | ||||
| 53 | +## Calibration and empirical validation | ||||
| 54 | +Maintain `docs/parameter_ledger.csv`: parameter, units, source, year/geography, moment, method, range, uncertainty. Use verified public macro, labor, wealth, interest rate and financial data where possible. Distinguish calibration from validation. Benchmark model with AI switched off against known analytical cases. Check wealth tails, factor shares, asset return moments, liquidity, and leverage cycles. Where real data are unavailable, explicitly use illustrative calibration and sensitivity analysis. Include a separate roadmap for empirical validation with genuine adoption, transaction or investment data, subject to rights and availability. | ||||
| 55 | + | ||||
| 56 | +## Required visualizations and results | ||||
| 57 | +Produce vector-quality figures: architecture and ownership flows; within-period timing; delegation thresholds; wage and interest rate responses; labor/capital/AI income shares; Lorenz curves; welfare by wealth percentile; asset prices, spreads, liquidity and volatility; collateral amplification; common-model herding; sensitivity heatmaps; equilibrium residuals; and inference cost frontier. Tables: notation, novelty matrix, parameters, baseline equilibrium, counterfactuals, welfare, ablations, robustness and computational costs. All results must come from executable code, never invented numbers. | ||||
| 58 | + | ||||
| 59 | +## Repository structure | ||||
| 60 | +``` | ||||
| 61 | +agentic-ge/ | ||||
| 62 | + CLAUDE.md | ||||
| 63 | + README.md | ||||
| 64 | + pyproject.toml | ||||
| 65 | + configs/ | ||||
| 66 | + data/raw/ data/processed/ | ||||
| 67 | + src/age/{economy,agents,equilibrium,markets,banking,llm,experiments,analysis}/ | ||||
| 68 | + tests/{unit,integration,property}/ | ||||
| 69 | + docs/{literature_matrix.md,model_specification.md,parameter_ledger.csv,research_log.md,limitations.md} | ||||
| 70 | + experiments/pre_registration.md | ||||
| 71 | + results/{figures,tables}/ | ||||
| 72 | + paper/main.tex | ||||
| 73 | + paper/sections/ | ||||
| 74 | + paper/appendices/ | ||||
| 75 | + paper/references.bib | ||||
| 76 | +``` | ||||
| 77 | +Use Python, NumPy, SciPy, pandas, Matplotlib, pytest, and a robust schema validator. JAX optional when justified. Support deterministic seeds, config-driven CLI, checkpointing, experiment manifests, Git revision and reproducible environment locks. Start on a single workstation; optional distributed inference only after a working local baseline. Keep market clearing and accounting separate from LLM generation. | ||||
| 78 | + | ||||
| 79 | +## Paper manuscript | ||||
| 80 | +Write a full English LaTeX paper titled **When AI Agents Become Economic Agents: An Agentic General Equilibrium Theory** with: abstract written after results; introduction; literature; institutions and environment; benchmark equilibrium; heterogeneous agents and ownership; asset markets and credit; equilibrium computation; LLM agent design; calibration; counterfactual results; welfare and distribution; robustness; limitations; conclusion; appendices with proofs, numerical algorithms, prompts, schemas, replication instructions and extra figures. Use verified BibTeX entries. Compile to PDF if TeX is installed; otherwise provide buildable sources. Do not present fabricated estimates or theorems as findings. | ||||
| 81 | + | ||||
| 82 | +## Milestones and acceptance gates | ||||
| 83 | +1. **Novelty gate:** verified literature matrix, precise contribution and competing explanations. | ||||
| 84 | +2. **Theory gate:** complete definitions, consistent budgets, resource constraints, clear equilibrium and at least one valid derived result. | ||||
| 85 | +3. **Numerics gate:** baseline solver, convergence checks, accounting identities, zero-AI limiting case and reproducibility. | ||||
| 86 | +4. **Agent gate:** schema validation, risk enforcement, audit logs, prompt/version stability and baseline comparisons. | ||||
| 87 | +5. **Science gate:** controlled experiments, uncertainty, negative results, sensitivity and mechanism isolation. | ||||
| 88 | +6. **Writing gate:** complete paper, figure/table provenance, verified references, replication package and hostile-referee critique. | ||||
| 89 | + | ||||
| 90 | +Do not proceed to extravagant multi-agent simulations before gates 1–3 are met. If a gate fails, report why and repair the design. | ||||
| 91 | + | ||||
| 92 | +## Execution protocol | ||||
| 93 | +At each stage: (a) state the precise scientific question, (b) write down assumptions, (c) implement and test, (d) show numerical evidence or mathematical proof, (e) discuss threats to interpretation, (f) log decisions and next tasks. Maintain a live TODO list. Do not ask for confirmation for ordinary implementation choices; choose transparent defaults and record them. Request user input only for indispensable private data, external credentials, expensive compute authorization, or major scope changes. Never claim a test passed unless it ran. If internet or TeX is unavailable, state the limitation and continue with honest local deliverables. | ||||
| 94 | + | ||||
| 95 | +## Start now | ||||
| 96 | +First produce the verified/clearly provisional literature and novelty audit, a 2–3 page research blueprint, a minimal analytically tractable economy with explicit balance-sheet equations and equilibrium definition, and a repository scaffold. Then derive the first proposition and implement a deterministic baseline with tests. Only then add LLM agents, banking and the full heterogeneous-agent extension. Aim for a parsimonious groundbreaking mechanism, not complexity for its own sake. | ||||
added
research/corpus/WP26_CLAUDE.md
+135 −0
@@ -0,0 +1,135 @@ | |||||
| 1 | +# CLAUDE.md — Can Autonomous AI Agents Discover the Fundamental Value of Real Estate? | ||||
| 2 | + | ||||
| 3 | +## Mission and non-negotiable scientific standard | ||||
| 4 | +Act as a multidisciplinary research team in real estate economics, appraisal, econometrics, machine learning, causal inference, multi-agent systems, and reproducible software engineering. Build an original, publication-quality research program and working codebase titled **Can Autonomous AI Agents Discover the Fundamental Value of Real Estate? Evidence from Quebec Transactions and Multi-Agent Deliberation**. The study must test, rather than assume, whether structured deliberation among autonomous AI agents improves valuation accuracy, uncertainty calibration, explanation faithfulness, and decision usefulness relative to strong statistical, machine-learning, single-LLM, and human baselines. | ||||
| 5 | + | ||||
| 6 | +Never invent data, results, citations, human assessments, API capabilities, or model performance. Clearly distinguish a transaction price, an appraisal estimate, an investment value, and an unobservable latent fundamental value. Transaction prices are noisy proxies, not ground-truth fundamental values. State identification assumptions and develop multiple operational definitions of value. A negative finding is publishable if the design is rigorous. | ||||
| 7 | + | ||||
| 8 | +## Research questions and hypotheses | ||||
| 9 | +RQ1: Do specialized multi-agent systems outperform single LLMs, hedonic models, repeat-sales approaches, gradient boosting, and conventional AVMs on genuinely unseen Quebec transactions? | ||||
| 10 | +RQ2: Is any improvement due to deliberation, complementary information, greater inference compute, ensembling, or privileged access to data? | ||||
| 11 | +RQ3: Does role diversity improve calibration and reduce large valuation errors, including in thin markets and under distribution shift? | ||||
| 12 | +RQ4: Can agents provide faithful, auditable explanations grounded in property attributes, comparable sales, market trends, and uncertainty? | ||||
| 13 | +RQ5: Does performance vary across regions, price tiers, building types, market cycles, and transaction liquidity? | ||||
| 14 | +RQ6: Are agentic valuations economically useful for lending and appraisal after accounting for inference cost, latency, human review, and fairness? | ||||
| 15 | + | ||||
| 16 | +Pre-register primary endpoints and hypotheses before running final test evaluations. Primary outcome: out-of-time absolute log-price error on arm's-length residential transactions. Co-primary or secondary: MAE in CAD, MdAPE, RMSE log, tail error (P90/P95), interval coverage, interval width, CRPS or pinball loss, cost and latency. Specify all definitions precisely. | ||||
| 17 | + | ||||
| 18 | +## Data sources and legal constraints | ||||
| 19 | +Use authorized, documented access to **Vrai-Prix** actual Quebec sales transactions and **Immo-Ka** listing/property information where useful. These are potential sources, not automatically accessible. Begin with a data-access audit; inspect available schemas, endpoints, exports, documentation, usage rights, update frequency, geographic scope, and join keys. Ask for access instructions and credentials only when required; use environment variables and a local secrets manager, never put secrets in source control or manuscript. Do not bypass authentication, scrape restricted endpoints, or infer consent. Do not send personal identifiers, private listing remarks, occupant information, or confidential records to external LLM APIs without authorization and suitable safeguards. | ||||
| 20 | + | ||||
| 21 | +Candidate variables: sale price, deed/closing date, listing date and ask price, location at permitted geographic precision, property type, land area, living area, construction year, renovations, bedrooms/bathrooms, condition, quality, energy features, garage, basement, municipal assessment, tax amounts, neighborhood amenities, transit, schools, flood/fire exposure, mortgage rates, regional housing supply, and local sales liquidity. Track missingness and provenance. Only use features observable as of the valuation timestamp; prevent post-sale information and target leakage. Listing data are optional and must not create unfair advantages across arms. | ||||
| 22 | + | ||||
| 23 | +Implement ingestion adapters for CSV/Parquet/SQL and optional authenticated APIs. Store raw snapshots immutable with data dictionaries, versioned transformations, provenance, licenses, and record-level lineage. Deduplicate repeated transfers and listings; link sales/listings probabilistically with confidence and manual validation sample. Identify non-arm's-length, related-party, distressed, and anomalous transfers; analyze exclusion sensitivity. Respect Quebec privacy requirements and organizational research-ethics review where applicable. Publish only de-identified or synthetic examples if redistribution is not authorized. | ||||
| 24 | + | ||||
| 25 | +## Theoretical contribution: valuation as decentralized information aggregation | ||||
| 26 | +Define a latent market-consistent value V*_{i,t} conditional on an explicit information set and market state. Distinguish a structural fundamental-value construct (discounted expected housing services / net rents and resale proceeds, with user cost, risk, and liquidity) from a transaction-price prediction target. Formulate an information-aggregation model in which agents k receive partially overlapping signals s_{ik}, have correlated errors, strategic or behavioral biases, and communicate through a constrained deliberation protocol. Derive testable conditions under which deliberation reduces or increases mean-squared error, particularly with correlated signals, anchoring, common-model dependence, and information cascades. Do not claim general existence/uniqueness theorems without proof. Propose falsifiable propositions about diversity, correlation, communication topology, and aggregation weights. | ||||
| 27 | + | ||||
| 28 | +## Multi-agent architecture | ||||
| 29 | +Implement a modular 5–20-role architecture with default **12 agents**: | ||||
| 30 | +1. Certified-appraisal-method specialist (sales comparison, cost, income when relevant) | ||||
| 31 | +2. Comparable-sales selection and adjustment specialist | ||||
| 32 | +3. Hedonic/econometric valuation specialist | ||||
| 33 | +4. Local housing-market economist | ||||
| 34 | +5. Building-condition/inspection specialist (only verified observations; no invented inspection) | ||||
| 35 | +6. Geospatial/accessibility and environmental-risk specialist | ||||
| 36 | +7. Mortgage underwriting and collateral-risk specialist | ||||
| 37 | +8. Buyer / household willingness-to-pay analyst | ||||
| 38 | +9. Seller / listing-strategy analyst | ||||
| 39 | +10. Rental-income / user-cost analyst | ||||
| 40 | +11. Data-quality, leakage, and provenance auditor | ||||
| 41 | +12. Independent skeptical reviewer / red-team agent | ||||
| 42 | + | ||||
| 43 | +Add optional roles up to 20 (construction-cost estimator, urban planning/zoning, macro rates, energy efficiency, climate risk, regional expert, uncertainty auditor, fairness auditor). Agents are **simulated analytic roles**, not licensed Quebec appraisers or real lenders; never misrepresent professional certification. | ||||
| 44 | + | ||||
| 45 | +Each agent receives a role-specific, least-privilege evidence packet, standardized valuation date, explicit information cutoff, comparable pool, permitted tools, and a structured JSON schema: point estimate, distribution/quantiles, assumptions, evidence IDs, adjustments, missing data, confidence rationale, counterarguments, and cost. Enforce machine-readable validation, bounded retries, and citations to internal evidence IDs. Missing inspection observations must remain missing. | ||||
| 46 | + | ||||
| 47 | +## Providers and orchestration | ||||
| 48 | +Support **Anthropic Claude API** and **OpenAI API** through provider adapters with configurable model IDs (never assume latest model identifiers), structured-output validation, rate-limit handling, retry/backoff, token budgets, logging, and privacy-aware caching. Use official SDKs and documented capabilities. Keep provider configuration in `.env.example` with `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` placeholders. Never log raw credentials. Record model IDs, API parameters, prompt hashes, temperature, tool calls, token usage, cost estimates, and latency. Design runs that compare all-Claude, all-OpenAI, and mixed-provider committees at matched cost and information budgets; randomize provider-to-role assignment where feasible. | ||||
| 49 | + | ||||
| 50 | +Use Python 3.12+, typed Pydantic schemas, a provider-neutral orchestration layer, async concurrency with strict limits, deterministic non-LLM tools, and SQLite/PostgreSQL for experiment metadata. Optional UI: simple Streamlit or React dashboard for valuation dossiers and debates. No live autonomous trading, lending decisions, or real estate offers; research only. | ||||
| 51 | + | ||||
| 52 | +## Deliberation protocols and experimental treatments | ||||
| 53 | +Implement and evaluate at least: | ||||
| 54 | +A. Hedonic OLS / regularized regression (proper spatial/time controls) | ||||
| 55 | +B. Repeat-sales or hierarchical hedonic where sample supports it | ||||
| 56 | +C. CatBoost/XGBoost/LightGBM tuned on validation only | ||||
| 57 | +D. Strong tabular AVM with spatial-temporal features and calibrated uncertainty | ||||
| 58 | +E. Single LLM, evidence-matched | ||||
| 59 | +F. Independent LLM agents aggregated without communication | ||||
| 60 | +G. Structured debate: independent estimates → evidence exchange → critique → revised estimates → aggregation | ||||
| 61 | +H. Debate with a blinded skeptic and explicit evidence verification | ||||
| 62 | +I. Random/shuffled-role or placebo deliberation | ||||
| 63 | +J. Cost-matched single-agent repeated reasoning and cost-matched ensemble | ||||
| 64 | + | ||||
| 65 | +Use the same authorized information cutoff and comparable selection opportunity across treatments. Test arithmetic mean, median, trimmed mean, inverse-variance weighting (estimated out of sample), stacking, and robust Bayesian aggregation. No final-test-informed aggregation weights. Explicitly separate improvements from more tokens, more tools, more models, or more data. Limit debate to pre-specified rounds (e.g. 0, 1, 2, 4) and evaluate diminishing returns, convergence, anchoring, and correlated hallucinations. | ||||
| 66 | + | ||||
| 67 | +## Experimental design and leakage defense | ||||
| 68 | +Use a chronological split with train/validation/test and a final untouched holdout; specify dates based on actual coverage. Add spatial holdouts (entire municipalities or regions), rolling-origin evaluation, and distribution-shift stress tests. Comparable retrieval must be strictly as-of-date; no same-property future transfers, post-sale listings, or near-duplicate records leaking across partitions. Group by property identity and assess neighborhood dependence. Build a leakage-audit suite and adversarial tests. If available, retain a separate prospective evaluation set gathered after model/prompt freeze. | ||||
| 69 | + | ||||
| 70 | +Stratify results by Montreal/Quebec City/Outaouais/other regions as data permit, urban vs rural, condominium vs detached vs multiplex, price deciles, transaction density, and property age. Avoid presenting unsupported granular estimates. Compute paired confidence intervals via clustered/block bootstrap (property, municipality, time as justified), Diebold-Mariano-style comparisons only where assumptions hold, and multiple-testing adjustments. Report effect sizes, statistical uncertainty, and practical significance. No p-hacking or test-set prompt tuning. | ||||
| 71 | + | ||||
| 72 | +## Human expert comparison | ||||
| 73 | +Where feasible, recruit licensed appraisal professionals and/or trained human appraisers under an approved protocol; do not fabricate a human benchmark. Give identical timestamped information packets, time budgets, and clear instructions. Randomize case order, blind sale prices, log confidence intervals, measure inter-rater reliability, and evaluate human-only, AI-only, and human+AI. Distinguish human appraiser judgement from retrospective transaction price. If human recruitment is unavailable, mark this arm as pending and do not claim it was performed. | ||||
| 74 | + | ||||
| 75 | +## Explainability and calibration | ||||
| 76 | +Assess whether explanations cite genuine, timestamp-valid evidence and whether stated adjustments are numerically consistent with the predicted value. Evaluate factuality, provenance precision/recall, counterfactual stability, sensitivity to spurious variables, and human-rated usefulness using blinded rubrics. Do not equate plausible prose with faithful reasoning. Quantify interval coverage at 50%, 80%, 90%, and 95%, conditional coverage by subgroup, sharpness, conformal prediction where appropriate, and calibration under drift. Report severe overvaluation/undervaluation rates relevant to collateral risk. | ||||
| 77 | + | ||||
| 78 | +## Fundamental-value identification extensions | ||||
| 79 | +Because realized price is not fundamental value, add triangulation: repeat transactions and subsequent resale (carefully accounting for intervening market movements), rental yields and discounted cash-flow where reliable rents exist, independent professional valuations if legally accessible, and price-to-rent/user-cost diagnostics. Explain selection bias and limits of each proxy. A model can forecast transaction prices well while failing to identify economic fundamentals; keep these conclusions separate. | ||||
| 80 | + | ||||
| 81 | +## Economic welfare and market design | ||||
| 82 | +Construct a stylized buyer-seller-lender model in which valuation accuracy and uncertainty affect search, bargaining, credit approval, collateral haircuts, and transaction outcomes. Calibrate transparently where evidence permits; otherwise label simulations as illustrative. Study information asymmetry, bargaining surplus, adverse selection, risk of common-model correlated mispricing, and market concentration in AI valuation providers. Do not imply causal welfare gains from predictive performance alone. | ||||
| 83 | + | ||||
| 84 | +## Software deliverables | ||||
| 85 | +Create a reproducible repository: | ||||
| 86 | +- `README.md`, `CLAUDE.md`, `pyproject.toml`, `.env.example`, `LICENSE` (only where rights permit) | ||||
| 87 | +- `configs/` for data splits, model IDs, treatments, budgets, and seeds | ||||
| 88 | +- `src/data/` ingestion, schema validation, joins, as-of joins, leakage checks | ||||
| 89 | +- `src/features/` spatial/temporal features, comparable retrieval | ||||
| 90 | +- `src/baselines/` hedonic, gradient boosting, AVM, uncertainty | ||||
| 91 | +- `src/agents/` role prompts, evidence packets, provider adapters, JSON contracts | ||||
| 92 | +- `src/debate/` protocols, critique, aggregation, stopping rules | ||||
| 93 | +- `src/evaluation/` metrics, calibration, stratification, clustered inference | ||||
| 94 | +- `src/experiments/` reproducible runners, cost tracking, audit trails | ||||
| 95 | +- `tests/` unit/integration/leakage/mock-provider tests | ||||
| 96 | +- `notebooks/` exploratory analysis (not authoritative pipelines) | ||||
| 97 | +- `paper/` complete LaTeX manuscript, BibTeX, figures, tables, appendices | ||||
| 98 | +- `reports/` experiment cards, failure analyses, model cards, limitations | ||||
| 99 | + | ||||
| 100 | +Implement mock LLM adapters and a clearly labeled synthetic dataset so the entire pipeline runs without keys or proprietary data. Include CLI commands for ingest, validate, train, run agents, evaluate, generate tables, and build PDF. Pin dependencies, set seeds, capture versions and hardware, and make outputs reproducible. Do not claim deterministic reproducibility for hosted LLMs; store response artifacts securely and measure run-to-run variation. | ||||
| 101 | + | ||||
| 102 | +## Manuscript requirements | ||||
| 103 | +Write in polished academic English with a serious, restrained style. Target Real Estate Economics, Journal of Real Estate Finance and Economics, or an appropriate finance/AI journal depending on demonstrated contribution. Include abstract, introduction, literature with verified citations/DOIs, theory and propositions, Quebec institutional setting, data, identification, architecture, pre-registered experiments, main results, ablations, calibration, human comparison (if executed), economic implications, limitations, conclusion, references, and detailed reproducibility appendices. Never fabricate empirical tables: use placeholders clearly marked `NOT YET ESTIMATED` until generated by scripts. All figures/tables must come from versioned outputs. Produce `main.tex`, bibliography, compilation script, and publication-ready PDF when toolchain is available. | ||||
| 104 | + | ||||
| 105 | +## Execution phases and acceptance gates | ||||
| 106 | +Phase 0: inventory actual files, access rights, API documentation, computing environment, and research constraints; produce an honest gap analysis. | ||||
| 107 | +Phase 1: literature review and novelty map; identify close prior multi-agent real-estate/AVM papers and avoid unsupported priority claims. | ||||
| 108 | +Phase 2: preregistration, formal estimands, theory and proof attempts, data dictionary, data-governance plan. | ||||
| 109 | +Phase 3: build clean as-of-date data pipeline, leakage tests, and strong tuned non-LLM baselines. | ||||
| 110 | +Phase 4: implement 5-agent minimal prototype, then 12-agent default and optional 20-agent extension; run synthetic smoke tests. | ||||
| 111 | +Phase 5: run provider-balanced, information-matched, compute-matched randomized ablations on validation; freeze protocol. | ||||
| 112 | +Phase 6: evaluate final temporal/spatial holdouts once, with clustered uncertainty and cost accounting. | ||||
| 113 | +Phase 7: human benchmark if authorized, welfare model, robustness, interpretability audits. | ||||
| 114 | +Phase 8: produce manuscript, supplementary appendix, reproducibility bundle, and limitations register. | ||||
| 115 | + | ||||
| 116 | +After each phase, produce a concise `reports/phase_XX.md` with completed artifacts, failed checks, decisions, outstanding assumptions, and exact commands. Stop and ask targeted questions only for indispensable access or decisions; otherwise proceed with explicitly documented defaults. Never fabricate completion. | ||||
| 117 | + | ||||
| 118 | +## Immediate first actions | ||||
| 119 | +1. Inspect the repository and report what exists vs what is missing. | ||||
| 120 | +2. Draft `research_plan.md`, `data_access_checklist.md`, `preregistration.md`, and `architecture.md`. | ||||
| 121 | +3. Search and verify the relevant academic literature if browsing is available; otherwise flag bibliography for verification. | ||||
| 122 | +4. Create runnable synthetic-data and mock-provider baselines before making paid API calls. | ||||
| 123 | +5. Present an API-cost budget with small pilot, medium validation, and final experiment tiers, without inventing vendor prices. | ||||
| 124 | +6. Ask for Vrai-Prix / Immo-Ka schemas or authorized credentials only when the integration stage is reached. | ||||
| 125 | +7. Start implementation, tests, and LaTeX scaffolding; prioritize scientific validity over theatrical agent dialogue. | ||||
| 126 | + | ||||
| 127 | +## Final guiding principle | ||||
| 128 | +The central result must isolate whether **communication among heterogeneous autonomous valuation agents adds measurable information**, rather than merely adding compute, correlated opinions, or persuasive narratives. Report failure as rigorously as success. | ||||
| 129 | + | ||||
| 130 | +--- | ||||
| 131 | + | ||||
| 132 | +## Repository conventions (added by the implementation, 2026-10-27) | ||||
| 133 | +- UQO Working Paper No. 26, folder `Recherche-UQO/immobilier/agentic-valuation-quebec`, git remote `gitsrv:srv/git/wp26_uqo.git`. | ||||
| 134 | +- Python package: `src/agentic_valuation/` (installed editable: `pip install -e .`). CLI: `av <command>` (see README). | ||||
| 135 | +- Secrets only in `.env` (gitignored). Snapshot provenance in `data/raw/README.md`. Every result file is produced by a numbered script in `scripts/`. | ||||
added
research/corpus/WP27_BRIEF_DESIGN-BRIEF.md
+59 −0
@@ -0,0 +1,59 @@ | |||||
| 1 | +# Design brief — The Invisible Hand of Machines (UQO WP 27) | ||||
| 2 | + | ||||
| 3 | +Internal brief shared by the author and the sub-agents writing the literature review, theory and | ||||
| 4 | +pre-analysis plan. It describes what the simulator *actually* implements (src/market_agents). | ||||
| 5 | + | ||||
| 6 | +## Economy implemented in the simulator | ||||
| 7 | +- Discrete ticks t = 0..T-1 (T = 300–1000). One risky asset (optionally K = 2–5 with a common factor in | ||||
| 8 | + dividend innovations) and cash. Prices in integer ticks (1 cent), quantities in integer lots, cash in | ||||
| 9 | + integer cents; exact conservation checked after every fill. | ||||
| 10 | +- Dividend every `div_interval` = 20 ticks: D = mu_{s} + x + J, x_t = rho x_{t-1} + sigma eps_t (rho = 0.98, | ||||
| 11 | + sigma = 2 cents, mu = 50 cents), optional two-state regime in mu (Markov), optional jumps. | ||||
| 12 | + Latent fundamental value V_t = mu/r + x_t rho/(1+r-rho) with r = 0.25 % per period (so P/D ≈ 400, | ||||
| 13 | + V ≈ 200.00). Public value V^pub_t = same formula on the Kalman/HMM posterior from announced dividends | ||||
| 14 | + and public news. Agents never see V_t. | ||||
| 15 | +- Information: public news items (noisy reports of x_t, some deliberately biased = misleading); | ||||
| 16 | + private signals s_i = x_t + N(0, sigma²/precision) for "informed" agents (fundamentalists and a share of | ||||
| 17 | + LLM agents). No agent sees future draws. | ||||
| 18 | +- Exchange: continuous double auction, price–time priority, limit/market/cancel, partial fills, IOC | ||||
| 19 | + market remainder, taker fee 2 bp, maker fee 0, per-agent latency in [0.05, 1] tick (orders arrive | ||||
| 20 | + at decision time + latency and are processed in arrival order), order TTL 50 ticks, price band ±50 %, | ||||
| 21 | + optional circuit breaker (halt when |10-tick move| > threshold), no short selling by default, | ||||
| 22 | + leverage cap 3× for "leveraged" slots with maintenance margin 25 % and forced partial liquidation. | ||||
| 23 | +- Population (N = 100 / 1,000 / 10,000 trader slots): fundamentalists 25 % (30 % informed, precision 2), | ||||
| 24 | + trend followers 15 %, mean-reverters 10 %, noise traders 35 %, market makers 5 % (bounded | ||||
| 25 | + inventory-skewed two-sided quotes), leveraged trend followers 10 %, cross-asset arbitrageurs (multi-asset | ||||
| 26 | + only). Endowments: cash 20,000 + 100 shares scaled by a lognormal wealth multiplier (sd 0.3). | ||||
| 27 | +- LLM treatment: a fraction `llm_share` of trader *slots* (stratified across policy types, never market | ||||
| 28 | + makers) is replaced by an LLM policy that decides every 20 ticks (staggered offsets) from a canonical | ||||
| 29 | + snapshot (book depth 5 levels, mid history, recent trades, last dividend, public PV, news, own private | ||||
| 30 | + signal if any, own account and open orders). Output = strictly validated JSON (hold/place/cancel …). | ||||
| 31 | + Invalid decisions = hold, logged. Realized LLM share of agents, orders and volume are all reported. | ||||
| 32 | + Providers: OpenAI (Responses API, json_schema), Anthropic (Messages API, json_schema), mock (seeded | ||||
| 33 | + rule with injected invalid answers). Treatments: provider mix, same vs diverse persona prompts, | ||||
| 34 | + memory (0 vs 5 past decisions), communication channel (cohorts of 5 share rationales), adaptive | ||||
| 35 | + P&L feedback, matched latency, equal token / USD / decision-opportunity budgets, frozen decision | ||||
| 36 | + library replay vs online calls. | ||||
| 37 | +- Randomization: master seed → independent streams (fundamentals, news, slots, policy assignment, LLM | ||||
| 38 | + slot assignment, activation, tie-breaks, per-agent RNG). Matched pairs across `llm_share` share | ||||
| 39 | + every stream except the LLM slot draw. ≥ 30 seeds exploratory, power-based for confirmatory. | ||||
| 40 | + | ||||
| 41 | +## Stylized theoretical model (to be written up by the theory agent, must map to the above) | ||||
| 42 | +One-period, one asset, liquidation value v ~ N(0, σ_v²) around the public PV. N traders receive | ||||
| 43 | +s_i = v + ε_i with ε_i = η_{g(i)} + u_i, where g(i) is the trader's "model" (foundation model / | ||||
| 44 | +prompt family), η_g ~ N(0, σ_η²) iid across models, u_i ~ N(0, σ_u²) iid. A share φ_g of traders uses | ||||
| 45 | +model g (Σ_g φ_g ≤ 1; the remaining 1 − Σφ_g traders have fully idiosyncratic errors, i.e. their own | ||||
| 46 | +private model). Traders submit market orders x_i = β s_i (β > 0 a fixed response intensity; the | ||||
| 47 | +behavioral assumption mirrors rule-like LLM policies and is relaxed in a CARA extension). Noise | ||||
| 48 | +traders submit z ~ N(0, σ_z²). A competitive, risk-neutral market maker sets P = E[v | Y], | ||||
| 49 | +Y = Σ_i x_i + z, so P = λ Y with λ = Cov(v,Y)/Var(Y). | ||||
| 50 | +Objects: price informativeness τ = 1 − Var(v | Y)/σ_v²; pricing error Var(P − v); order-flow | ||||
| 51 | +correlation ρ_x = Corr(x_i, x_j); synchrony; effective number of models M_eff = 1/Σ_g φ_g²; | ||||
| 52 | +feedback extension with trend demand γ(P_1 − P_0) and amplification 1/(1 − λγ); leverage extension | ||||
| 53 | +with margin m, wealth W, impact λ: amplification 1/(1 − λ X/m) and spiral when λ X/m ≥ 1, where X is | ||||
| 54 | +the aggregate same-signed leveraged position (increasing in the shared-model share). | ||||
| 55 | +Hypotheses the simulator tests: H1 informativeness falls in the share using a single shared model | ||||
| 56 | +(holding information quality fixed) and rises in M_eff; H2 order-flow correlation and synchrony rise | ||||
| 57 | +in φ; H3 bubble/crash frequency and liquidity spirals rise with φ × leverage; H4 prompt/model | ||||
| 58 | +diversity restores part of the loss; H5 communication channels raise synchrony; H6 circuit breakers | ||||
| 59 | +and position limits cut crash depth at a cost in time-to-absorb. | ||||
added
research/corpus/WP28_CLAUDE.md
+1055 −0
@@ -0,0 +1,1055 @@ | |||||
| 1 | +# CLAUDE.md — UQO RESEARCH WORKING PAPER 28 | ||||
| 2 | +## Research execution mandate: Distributed Maximum Likelihood, Local Bias Correction, and the Economics of Synchronization | ||||
| 3 | + | ||||
| 4 | +> **Mission type:** autonomous, multi-phase research program for Claude Code. | ||||
| 5 | +> | ||||
| 6 | +> **Required working paper identifier:** `WP28` / `WP0028` (adopt the exact naming convention found in the UQO research repository; do not create duplicate identifiers). | ||||
| 7 | +> | ||||
| 8 | +> **Principal researcher:** Simon-Pierre Boucher — Université du Québec en Outaouais (UQO). | ||||
| 9 | +> | ||||
| 10 | +> **Prior exploratory draft credits:** Simon-Pierre Boucher and GPT-6.1. Preserve this provenance and the user's requested GPT-6.1 attribution in the working draft. Confirm the applicable journal/venue authorship and AI-disclosure policy before a submission version; never falsely represent an AI system as a legally accountable human author. | ||||
| 11 | +> | ||||
| 12 | +> **Language:** English, throughout manuscript, proofs, code comments, figures, documentation and supplementary material. | ||||
| 13 | +> | ||||
| 14 | +> **Research domain:** theoretical econometrics, statistical optimization, distributed maximum likelihood, communication complexity, high-order bias correction, numerical statistics, heterogeneous computing. | ||||
| 15 | +> | ||||
| 16 | +> **Current date for literature cutoff:** 2026-10-28; search current material rather than assuming bibliographic currency. | ||||
| 17 | +> | ||||
| 18 | +> **Quality aspiration:** a genuinely original, technically rigorous, reproducible article potentially suitable for leading econometrics / statistics / statistical-computing journals. Quality is measured by new and correct results, not page count or grandiose claims. | ||||
| 19 | + | ||||
| 20 | +--- | ||||
| 21 | + | ||||
| 22 | +## 0. Non-negotiable operating instructions | ||||
| 23 | + | ||||
| 24 | +You are Claude Code acting as a research mathematician, econometrician, algorithm designer, literature reviewer, scientific software engineer, adversarial referee, and academic typesetter. This is NOT an instruction to paraphrase the exploratory note. It is a research mandate to independently validate, challenge, extend, and—if justified—replace its central ideas with a stronger, defensible contribution. | ||||
| 25 | + | ||||
| 26 | +**Execute in order, completing one phase's acceptance tests before starting the next.** Make substantive progress autonomously; do not stop after writing a research plan, a few claims, or a skeleton PDF. Use tools to actually inspect the repository, read the reference source, derive proofs, implement estimators, run tests and simulations, compile LaTeX, review output, and write reproducibility documentation. When a proof or experiment fails, report the failure and adapt the design rather than hiding it. Continue to a publishable-quality, internally consistent draft within the resources and access actually available. Never assert results from jobs that have not finished. | ||||
| 27 | + | ||||
| 28 | +### 0.1 Truthfulness and scientific integrity | ||||
| 29 | + | ||||
| 30 | +- No invented theorem, proof, assumption, dataset, benchmark, reference, DOI, parameter estimate, speedup, significance level, or journal acceptance. | ||||
| 31 | +- Do not claim that distributed gradients, one-step Newton, split-sample jackknife, Richardson extrapolation, `K = o(N^{7/8})`, or `K = o(N^{11/12})` are intrinsically novel. Investigate who has already obtained each idea or bound. | ||||
| 32 | +- Explicitly differentiate **proved results**, **numerically supported observations**, **heuristics**, **conditional conjectures**, and **future research**. | ||||
| 33 | +- An asymptotic partition-rate theorem is *not* a wall-clock acceleration theorem. A low communication-round count is *not* the same as a low total number of transmitted bytes, and neither is proof of a favorable energy or financial cost. | ||||
| 34 | +- Do not conflate model-correct i.i.d. likelihood inference with misspecified, dependent, heterogeneous or growing-dimensional settings. | ||||
| 35 | +- Every estimator must be reproducibly defined; every theorem must give precise assumptions; every proof must close all essential steps. | ||||
| 36 | +- A dead end with a mathematical explanation is better than a fabricated breakthrough. A strong negative result or counterexample may itself become the contribution. | ||||
| 37 | +- Treat `GPT-6.1` authorship as provenance from the existing draft and user instruction, not a substitute for human responsibility or journal compliance. | ||||
| 38 | + | ||||
| 39 | +### 0.2 Research process and files | ||||
| 40 | + | ||||
| 41 | +1. Inspect the current repository before creating files. Read its root `CLAUDE.md`, README, WP index, templates, `wp27` conventions, the existing WP28 slot if any, scripts and build infrastructure. | ||||
| 42 | +2. Respect local conventions; use `WP28` as the canonical ID in metadata, paper front matter, output names and progress logs. | ||||
| 43 | +3. Never overwrite an unrelated existing WP28 without first recording the collision. If WP28 is already occupied, preserve it and create a conflict report / safe working branch; do not silently renumber without authorization. | ||||
| 44 | +4. Keep all work self-contained under the repository's conventional working-paper directory. If no convention exists, use `working-papers/WP28-distributed-mle/`. | ||||
| 45 | +5. Keep `research_log.md` updated with dated decisions, theorem changes, computations, citations verified, failures and exact reproducibility commands. | ||||
| 46 | +6. Use the researcher's available CPU/GPU/cluster systems only when provisioned and authorized. Benchmark actual hardware; never assume the existence, credentials, health, bandwidth, or availability of a MacLustr node. | ||||
| 47 | +7. Do not expose API keys, SSH keys, passwords, endpoint secrets or private datasets in source files, logs, paper, artifacts or commits. | ||||
| 48 | +8. Avoid destructive commands, forced pushes and unrelated repository modifications. Do not publish a preprint or submit to a journal without explicit instruction. | ||||
| 49 | +9. Complete the project from initial inspection through PDF validation; stop only when a real blocker makes an indispensable step impossible. Document blocked items, and continue with whatever can be completed. | ||||
| 50 | + | ||||
| 51 | +--- | ||||
| 52 | + | ||||
| 53 | +## 1. Research brief and target positioning | ||||
| 54 | + | ||||
| 55 | +### 1.1 Working title | ||||
| 56 | + | ||||
| 57 | +**Beyond One-Step Distributed Maximum Likelihood: Higher-Order Bias Cancellation, Communication–Computation Frontiers, and Adaptive Econometric Inference** | ||||
| 58 | + | ||||
| 59 | +Alternative title if contributions warrant it: | ||||
| 60 | + | ||||
| 61 | +**The Price of Synchronization: Sharp Statistical and Computational Frontiers for Distributed Maximum Likelihood** | ||||
| 62 | + | ||||
| 63 | +Use a sober title supported by the final actual contribution. Keep the initial draft title, *Local Bias Correction versus Global Synchronization in Distributed Maximum Likelihood*, as the starting point, not as a fixed requirement. | ||||
| 64 | + | ||||
| 65 | +### 1.2 Central research question | ||||
| 66 | + | ||||
| 67 | +> For regular nonlinear likelihood models with `N` observations and `K` distributed partitions, how can additional local computation replace global network synchronization while preserving the first-order inferential properties of centralized maximum likelihood? What is the optimal tradeoff between local bias order, number of global Newton-like corrections, numerical conditioning, communicated bytes, elapsed time, and interval coverage? | ||||
| 68 | + | ||||
| 69 | +The **research novelty target** is not merely a fractional exponent. Seek a mathematically precise, technically defensible **statistical–communication–computation frontier** and a practical policy for choosing local correction depth and global synchronization rounds under measurable machine and network constraints. Determine whether such a contribution is already established and formulate the exact gap before claiming novelty. | ||||
| 70 | + | ||||
| 71 | +### 1.3 Required outputs (not aspirational placeholders) | ||||
| 72 | + | ||||
| 73 | +- A fully sourced, original English research article, preferably approximately 25–40 substantive pages excluding appendices *if the research supports this length*; no padding. | ||||
| 74 | +- A mathematical appendix with complete proofs, exact regularity conditions, auxiliary lemmas, failure cases and counterexamples. | ||||
| 75 | +- Well-tested, documented, executable reference implementations of all estimators. | ||||
| 76 | +- Reproducible Monte Carlo experiments and, when feasible, actual distributed / multi-process / multi-node benchmarks. | ||||
| 77 | +- Clear publication-grade tables, vector figures, formulas and algorithm pseudocode. | ||||
| 78 | +- A verified `.bib` bibliography and a literature/priority audit. | ||||
| 79 | +- A deterministic one-command or documented small-command build producing the final PDF. | ||||
| 80 | +- Code, environments, checksums, seeds, raw and processed results, resources and run manifests sufficient for independent reproduction. | ||||
| 81 | +- A candid paper-specific `LIMITATIONS_AND_CLAIMS.md`, `THEOREM_AUDIT.md`, `PRIOR_ART_MATRIX.csv`, `EXPERIMENT_MANIFEST.csv` and `FINAL_REVIEW.md`. | ||||
| 82 | +- If a stronger mathematical contribution cannot be validated, deliver a rigorous and accurately framed working paper, not an inflated method paper. | ||||
| 83 | + | ||||
| 84 | +--- | ||||
| 85 | + | ||||
| 86 | +## 2. Source-of-truth: inspect the existing PAMLE paper and data | ||||
| 87 | + | ||||
| 88 | +The user has already prepared an exploratory paper and reproducibility archive. If supplied in the Claude Code environment, read them in full before modifying any mathematics: | ||||
| 89 | + | ||||
| 90 | +- `PAMLE_Boucher_GPT-6.1.pdf` | ||||
| 91 | +- `PAMLE_Boucher_GPT-6.1_LaTeX_and_Reproducibility.zip` | ||||
| 92 | + | ||||
| 93 | +The source archive is expected to contain files such as `pamle.tex`, `references.bib`, `monte_carlo.py`, `simulation_summary.csv`, `simulation_replicates.csv`, and a figure. These names describe the handoff; resolve actual paths instead of assuming they are mounted under the same directory. If missing, recover from the project context or the article text provided by the researcher; never invent missing numeric data. | ||||
| 94 | + | ||||
| 95 | +**Source chronology:** prior study dated 2026-10-28, by Simon-Pierre Boucher and GPT-6.1; a 16-page introductory research note. The existing Monte Carlo used independent exact-Gamma simulation for an exponential MLE, `N = 1,048,576`, local sizes `m in {256, 64, 16}`, seed `20261028`, and **500** replicates per design. Do not silently describe these as 1,000 replications or as physical-cluster experiments. Verify all numbers directly against the actual CSV and code before citing them. | ||||
| 96 | + | ||||
| 97 | +### 2.1 Baseline formulas to check, not blindly trust | ||||
| 98 | + | ||||
| 99 | +Use `N` for sample size, `K` for number of worker partitions, `m = N/K`, fixed parameter dimension `p`, truth `theta_0`, centralized MLE `theta_hat_N`: | ||||
| 100 | + | ||||
| 101 | +```text | ||||
| 102 | +L_N(theta) = N^{-1} sum_i log f(X_i; theta) | ||||
| 103 | +g_N(theta) = grad L_N(theta) | ||||
| 104 | +H_N(theta) = Hessian L_N(theta) | ||||
| 105 | + | ||||
| 106 | +local_mle[k] = argmax_{theta} m^{-1} sum_{i in block k} log f(X_i; theta) | ||||
| 107 | +local_jack2[k] = 2 * local_mle[k] - (half_A_mle[k] + half_B_mle[k]) / 2 | ||||
| 108 | +pilot = K^{-1} sum_k local_jack2[k] | ||||
| 109 | +final = pilot - inv(H_N(pilot)) @ g_N(pilot) | ||||
| 110 | +``` | ||||
| 111 | + | ||||
| 112 | +**Never explicitly invert the Hessian in production code:** use a stable linear solve / trust-region / damped step with condition checks. The displayed inverse is mathematical notation only. | ||||
| 113 | + | ||||
| 114 | +Previously derived sufficient rates (conditional, not novelty claims): | ||||
| 115 | + | ||||
| 116 | +| Initialization | Global Newton corrections | Sufficient `K` regime for first-order centralized equivalence | | ||||
| 117 | +|---|---:|---| | ||||
| 118 | +| Average ordinary local MLEs | 0 | `K = o(N^(1/2))` | | ||||
| 119 | +| Average ordinary local MLEs | 1 | `K = o(N^(3/4))` | | ||||
| 120 | +| Half-block jackknife, cancels `m^{-1}` bias | 1 | `K = o(N^(7/8))` | | ||||
| 121 | +| Quarter-block higher-order extrapolation, cancels `m^{-1}, m^{-2}` bias | 1 | `K = o(N^(11/12))` | | ||||
| 122 | +| Average ordinary local MLEs | 2 | `K = o(N^(7/8))` | | ||||
| 123 | + | ||||
| 124 | +These are **sufficient asymptotic restrictions under nontrivial assumptions**, NOT maximal possible machine counts, NOT minimax lower bounds, NOT evidence of speedups, and NOT automatically valid for growing `p` or heterogeneous workers. | ||||
| 125 | + | ||||
| 126 | +### 2.2 Essential stochastic decomposition | ||||
| 127 | + | ||||
| 128 | +Require a common asymptotic influence function and a local remainder: | ||||
| 129 | + | ||||
| 130 | +```text | ||||
| 131 | +theta_hat_n - theta_0 = (1/n) sum_i psi(X_i) + R_n, | ||||
| 132 | +E[psi(X)] = 0, | ||||
| 133 | +E||R_n||^2 <= C / n^2, | ||||
| 134 | +E[R_n] = b_1/n + b_2/n^2 + O(n^{-3}). | ||||
| 135 | +``` | ||||
| 136 | + | ||||
| 137 | +For the half-block jackknife, the influence term is preserved *exactly*. The corrected local remainder has a centered stochastic contribution of order `O_p(1 / (m * sqrt(K)))` after worker averaging; this must not be omitted: | ||||
| 138 | + | ||||
| 139 | +```text | ||||
| 140 | +pilot - theta_hat_N = O_p( m^{-2} + (m*sqrt(K))^{-1} + N^{-1} ). | ||||
| 141 | +``` | ||||
| 142 | + | ||||
| 143 | +Under suitable local Lipschitz Hessian and inverse Hessian control: | ||||
| 144 | + | ||||
| 145 | +```text | ||||
| 146 | +||final - theta_hat_N|| = O_p( ||pilot - theta_hat_N||^2 ). | ||||
| 147 | +``` | ||||
| 148 | + | ||||
| 149 | +Consequently: | ||||
| 150 | + | ||||
| 151 | +```text | ||||
| 152 | +sqrt(N) ||final - theta_hat_N|| | ||||
| 153 | + = O_p( K^4/N^(7/2) + K/N^(3/2) + N^(-3/2) ). | ||||
| 154 | +``` | ||||
| 155 | + | ||||
| 156 | +This supports `K = o(N^(7/8))`, provided consistency and all conditions hold uniformly along the relevant triangular array. Every `O_p` statement must be checked carefully, including dependence across half-sample and full-sample estimators and possible `p`-dependence in constants. | ||||
| 157 | + | ||||
| 158 | +### 2.3 Higher-order extrapolation to scrutinize | ||||
| 159 | + | ||||
| 160 | +For local whole-block, half-block and quarter-block averages `T_1, T_2, T_4`, respectively: | ||||
| 161 | + | ||||
| 162 | +```text | ||||
| 163 | +J_3 = (8/3) T_1 - 2 T_2 + (1/3) T_4. | ||||
| 164 | +``` | ||||
| 165 | + | ||||
| 166 | +Check the Vandermonde moment equations: | ||||
| 167 | + | ||||
| 168 | +```text | ||||
| 169 | +sum w_j = 1, | ||||
| 170 | +sum w_j * s_j = 0, | ||||
| 171 | +sum w_j * s_j^2 = 0, | ||||
| 172 | +``` | ||||
| 173 | + | ||||
| 174 | +where `s_j` is the partition multiplier. This cancels the first two expected bias terms **if an appropriate expansion holds**. Quantify finite-sample variance amplification and coefficient growth. If high-order corrections produce unstable or non-feasible parameter vectors, address it explicitly. Do not claim higher order is always better. | ||||
| 175 | + | ||||
| 176 | +### 2.4 Exact exponential example that must be independently rederived | ||||
| 177 | + | ||||
| 178 | +For `X_i ~ Exp(rate = theta_0)`: | ||||
| 179 | + | ||||
| 180 | +```text | ||||
| 181 | +theta_hat_n = 1 / Xbar_n | ||||
| 182 | +E[theta_hat_n] = theta_0 * n/(n-1), n > 1 | ||||
| 183 | +Bias(jack2) = -2 theta_0 / [(m-1)(m-2)], m > 2 | ||||
| 184 | +Newton(x) = 2x - x^2 Xbar_N | ||||
| 185 | +Newton(x) - theta_hat_N = -(x-theta_hat_N)^2 / theta_hat_N | ||||
| 186 | +``` | ||||
| 187 | + | ||||
| 188 | +At the boundary `K/N^(7/8) -> c > 0`, the previous paper derived: | ||||
| 189 | + | ||||
| 190 | +```text | ||||
| 191 | +sqrt(N) (theta_one_step_jack2 - theta_hat_N) | ||||
| 192 | + ->p -4 theta_0 c^4. | ||||
| 193 | +``` | ||||
| 194 | + | ||||
| 195 | +Reproduce and verify this limit, including centering, constants and distributional conditions. Important caveat: the exponential family has a trivially aggregable finite-dimensional sufficient statistic, so it is NOT evidence of communication optimality or a need for approximate MLE. Use it as a mathematical sanity test and exact counterexample laboratory. | ||||
| 196 | + | ||||
| 197 | +--- | ||||
| 198 | + | ||||
| 199 | +## 3. PHASE 0 — Repository reconnaissance and reproducibility lock | ||||
| 200 | + | ||||
| 201 | +**Actions** | ||||
| 202 | + | ||||
| 203 | +1. Detect repository root and project structure; inventory other working papers, especially `WP27`, the registry/index, document preamble, citation style, quality requirements, and naming patterns. | ||||
| 204 | +2. Search for prior paper, archive and relevant internal data, but never scrape or transmit private material to external services without authorization. | ||||
| 205 | +3. Extract the existing archive to an immutable `references/initial_pamle/` directory if available; record checksums. | ||||
| 206 | +4. Read `pamle.tex` line by line for definitions, theorem statements, source provenance, experimental settings and any mathematical defects. | ||||
| 207 | +5. Run the existing simulation at its original seed and parameters. Verify row counts, method names, table numbers, plots and deterministic outputs (allowing documented floating-point tolerance). | ||||
| 208 | +6. Compile the old PDF separately if toolchain permits; identify existing warnings and shortcomings. | ||||
| 209 | +7. Create the target WP28 directory using repository conventions. Do not rename other WP IDs. | ||||
| 210 | +8. Write `PROJECT_MAP.md`, `SOURCE_PROVENANCE.md`, `PHASE_STATUS.md`, and `research_log.md`. | ||||
| 211 | + | ||||
| 212 | +**Gate 0: pass only when** all old claims and artifacts are inventoried, every existing number is tagged as replicated / not replicated / unavailable, and a WP28 workspace exists without clobbering other work. | ||||
| 213 | + | ||||
| 214 | +--- | ||||
| 215 | + | ||||
| 216 | +## 4. PHASE 1 — Exhaustive state-of-the-art / priority investigation | ||||
| 217 | + | ||||
| 218 | +Before deciding the main theorem is new, research the following intersecting bodies of literature through publisher pages, journal archives, arXiv, RePEc, Crossref/OpenAlex where accessible, and backward/forward citations. Do not trust search snippets or automated summaries in place of reading the relevant proofs. Record publication and preprint dates to evaluate priority. Search from foundational literature through **2026-10-28**. | ||||
| 219 | + | ||||
| 220 | +### 4.1 Minimum anchor references to verify | ||||
| 221 | + | ||||
| 222 | +1. Zhang, Duchi and Wainwright (2013), *Communication-Efficient Algorithms for Statistical Optimization*, Journal of Machine Learning Research 14:3321–3363; https://www.jmlr.org/papers/v14/zhang13b.html . Check averaging, subsampling bias correction, rate claims and communication accounting. | ||||
| 223 | +2. Huang and Huo (2019), *A Distributed One-Step Estimator*, Mathematical Programming 174:41–76; DOI `10.1007/s10107-019-01369-0`; preprint https://arxiv.org/abs/1511.01443 . Check the exact initialization assumptions, local/global curvature and one-step proof. | ||||
| 224 | +3. Dhaene and Jochmans (2015), *Split-panel Jackknife Estimation of Fixed-effect Models*, Review of Economic Studies 82(3):991–1030; DOI `10.1093/restud/rdv007`. Check split-sample theory, higher-order extrapolation and limitations in dependent panels. | ||||
| 225 | +4. Jordan, Lee and Yang (2019), *Communication-Efficient Distributed Statistical Inference*, JASA 114(526):668–681; DOI `10.1080/01621459.2018.1429274`. Study surrogate likelihood / CSL as an important competing communication-reduction strategy. | ||||
| 226 | +5. Fan, Guo and Wang, *Communication-Efficient Accurate Statistical Estimation*, verify current journal and bibliographic details. Read the full algorithm and convergence results, particularly multi-round corrections. | ||||
| 227 | +6. Rosenblatt and Nadler (2016), *On the optimality of averaging in distributed statistical learning*, Information and Inference; DOI `10.1093/imaiai/iaw013`. | ||||
| 228 | +7. Related work on distributed debiasing, bias-corrected one-shot estimation, Richardson extrapolation, high-order influence functions, federated M-estimation, communication lower bounds, Hessian sketching, K-step one-step estimators, and heterogeneity. | ||||
| 229 | + | ||||
| 230 | +### 4.2 Specific novelty threats to investigate | ||||
| 231 | + | ||||
| 232 | +- The Zhang–Duchi–Wainwright *subsampling/bootstrapping* approach already improves communication-efficient statistical error rates. Determine whether their techniques implicitly or explicitly subsume our bias cancellation. | ||||
| 233 | +- Some one-shot or multi-round distributed estimators may already attain the same `K` regime, with weaker assumptions or better time complexity. | ||||
| 234 | +- Split-sample / higher-order jackknife corrections are known. The weights alone are not publishable novelty. | ||||
| 235 | +- Multi-round Newton may replicate higher-order bias advantages; quantify this with matched communication budgets. | ||||
| 236 | +- A distributed *one-step* method still requires an uplink of local estimates, a broadcast of the common pilot, and an uplink of derivatives. Carefully define whether this is “two communication phases,” “one additional round,” or multiple network exchanges. Never advertise it as a literal zero- or one-message protocol. | ||||
| 237 | +- In regular parametric exponential families, sufficient statistics yield exact distributed MLE; compare against this trivial baseline and acknowledge the limitation. | ||||
| 238 | +- Finite sample `m`, increasing `K`, and high dimensional `p` may break second-order expansions or stable Hessian inversion. | ||||
| 239 | + | ||||
| 240 | +### 4.3 Required literature outputs | ||||
| 241 | + | ||||
| 242 | +`literature/PRIOR_ART_MATRIX.csv` with at least: | ||||
| 243 | + | ||||
| 244 | +```text | ||||
| 245 | +citation_key,authors,year,title,venue,doi_or_url,verified_full_text, | ||||
| 246 | +assumptions,number_of_rounds,upstream_bytes,local_computation, | ||||
| 247 | +statistical_rate,proof_type,applicable_models,overlap_with_WP28, | ||||
| 248 | +novelty_threat,notes,page_numbers_checked | ||||
| 249 | +``` | ||||
| 250 | + | ||||
| 251 | +Plus `literature/PRIORITY_AND_GAP.md` with: | ||||
| 252 | + | ||||
| 253 | +- 20–40 **verified relevant references as a search target**, not fabricated filler; include additional sources only if material. | ||||
| 254 | +- At least five papers compared at theorem/algorithm level, not only abstract level. | ||||
| 255 | +- A *claim-by-claim* map: known, possibly new, demonstrably new with specified proof, or undecided. | ||||
| 256 | +- One precisely stated **Candidate Contribution A** (strongest), **B** (feasible backup) and **C** (negative result / optimality counterexample). | ||||
| 257 | +- An explicit GO / REVISE / DROP decision for each proposed claim. | ||||
| 258 | + | ||||
| 259 | +**Gate 1:** no unqualified novelty language is allowed until the closest competing theorems have been inspected and cited. | ||||
| 260 | + | ||||
| 261 | +--- | ||||
| 262 | + | ||||
| 263 | +## 5. PHASE 2 — Build a mathematical specification and attack the assumptions | ||||
| 264 | + | ||||
| 265 | +### 5.1 Baseline model | ||||
| 266 | + | ||||
| 267 | +Start with i.i.d. observations and a correctly specified fixed-dimensional regular likelihood: | ||||
| 268 | + | ||||
| 269 | +- `X_1,...,X_N ~ P_{theta_0}` independent; | ||||
| 270 | +- `theta_0` interior to an open parameter set in `R^p`; | ||||
| 271 | +- information matrix `I(theta_0)` positive definite; | ||||
| 272 | +- enough differentiability and envelope/moment conditions for the score/Hessian expansions; | ||||
| 273 | +- local estimators exist and are measurable and consistently select the correct branch; | ||||
| 274 | +- local and global Hessian inverses are uniformly controlled with high probability; | ||||
| 275 | +- partitioning is random or deterministic independent of the observations, with equal block sizes for the first theorem; | ||||
| 276 | +- integers `K = K_N`, `m = N/K`, and `m -> infinity` along the triangular array. | ||||
| 277 | + | ||||
| 278 | +Separate assumptions for stochastic linearization, bias expansion, Hessian smoothness, central-limit theorem, moments and parameter-domain feasibility. State precisely which theorem uses which assumption. | ||||
| 279 | + | ||||
| 280 | +### 5.2 Definitions and proof checks | ||||
| 281 | + | ||||
| 282 | +Derive, with all terms shown: | ||||
| 283 | + | ||||
| 284 | +1. Influence expansion of MLE local estimates, including a mean-square bound on nonlinear remainder. | ||||
| 285 | +2. Bias expansions `b_j / m^j` uniform enough to handle multiple partition sizes. | ||||
| 286 | +3. Exact cancellation of the first-order stochastic term under the linear combination of whole-block and sub-block estimators. | ||||
| 287 | +4. Bounds for centered corrections and the covariances between nested local samples. | ||||
| 288 | +5. Bounds for differences relative to the *centralized MLE*, not just relative to `theta_0`. | ||||
| 289 | +6. The quadratic Newton remainder from integral Taylor expansion, including Hessian invertibility at both the pilot and points along the path. | ||||
| 290 | +7. Feasibility and positivity of parameters after extrapolation, including constrained or reparameterized MLEs. | ||||
| 291 | +8. Consequences for feasible variance estimation and confidence-interval coverage. | ||||
| 292 | +9. Critical boundaries and local alternatives, distinguishing sufficient, necessary-for-this-construction, and truly minimax-optimal results. | ||||
| 293 | + | ||||
| 294 | +### 5.3 Required edge cases / mathematical traps | ||||
| 295 | + | ||||
| 296 | +- Bias coefficient cancellations do not automatically imply a high-order `L2` remainder. | ||||
| 297 | +- `O_p` constants must not secretly diverge with `p`, partition count or bias-correction order. | ||||
| 298 | +- Asymptotic exponents require the small-o condition, not merely `K <= N^alpha` with a fixed nonvanishing proportionality. | ||||
| 299 | +- A shared global influence term can cancel; if local distributions differ, that identity may fail. | ||||
| 300 | +- For local MLE non-existence (e.g. complete separation in logit), document exact finite-sample safeguards and their statistical implications. | ||||
| 301 | +- Jackknife weights can be negative, so a rate, variance or probability estimate may leave its parameter space. | ||||
| 302 | +- A multi-step method can diverge if its initial point lies outside the attraction basin; use cautious local statements or explicit globalization. | ||||
| 303 | +- Distinguish observed Hessian, expected Fisher information, and sandwich uncertainty under misspecification. | ||||
| 304 | +- Do not use exact sufficient-statistic examples to make universal computational lower-bound claims. | ||||
| 305 | + | ||||
| 306 | +### 5.4 Mathematical validation support | ||||
| 307 | + | ||||
| 308 | +Use symbolic algebra and high-precision numeric checks to verify coefficients, moment formulas, Taylor identities and boundary constants. Mathematica/SymPy/Sage/Lean may supplement proofs, but machine-checked simplification is not a substitute for a mathematical justification. If Lean is installed, formalize at least one deterministic algebraic lemma as a bonus, not as a blocker. | ||||
| 309 | + | ||||
| 310 | +**Gate 2:** every proposed theorem has assumptions, conclusion, proof strategy, test cases and a `proved / conditional / open / false` label in `THEOREM_AUDIT.md`. | ||||
| 311 | + | ||||
| 312 | +--- | ||||
| 313 | + | ||||
| 314 | +## 6. PHASE 3 — Derive a GENERAL HIGH-ORDER BIAS-CORRECTION FAMILY | ||||
| 315 | + | ||||
| 316 | +This is a core mathematical task; derive the construction rather than copying the `r=2,3` formulas. | ||||
| 317 | + | ||||
| 318 | +### 6.1 Split-granularity extrapolation | ||||
| 319 | + | ||||
| 320 | +For positive integers `s_1,...,s_r` dividing `m`, define `T_{s_j,k}` as the average of the `s_j` local MLEs computed on equal disjoint sub-blocks of size `m/s_j`. For `s_1 = 1`, it is the full-block MLE. | ||||
| 321 | + | ||||
| 322 | +Assume for a sub-block size `n`: | ||||
| 323 | + | ||||
| 324 | +```text | ||||
| 325 | +E(theta_hat_n) = theta_0 + b_1/n + ... + b_{r-1}/n^(r-1) + O(n^(-r)). | ||||
| 326 | +``` | ||||
| 327 | + | ||||
| 328 | +Let `w_1,...,w_r` solve: | ||||
| 329 | + | ||||
| 330 | +```text | ||||
| 331 | +sum_j w_j = 1, | ||||
| 332 | +sum_j w_j s_j^a = 0 for a=1,...,r-1. | ||||
| 333 | +``` | ||||
| 334 | + | ||||
| 335 | +Define the local corrected estimator: | ||||
| 336 | + | ||||
| 337 | +```text | ||||
| 338 | +J_{r,k} = sum_j w_j T_{s_j,k}. | ||||
| 339 | +``` | ||||
| 340 | + | ||||
| 341 | +Prove, subject to precise assumptions: | ||||
| 342 | + | ||||
| 343 | +- the `r-1` leading expected bias coefficients cancel; | ||||
| 344 | +- the common first-order influence function is preserved; | ||||
| 345 | +- centered correction remainder has `L2` norm at most `O(m^{-1})` for **fixed `r` and controlled weights**; | ||||
| 346 | +- worker averaging yields `O_p((m sqrt(K))^{-1})` centered remainder; | ||||
| 347 | +- mean bias is `O(m^{-r})`. | ||||
| 348 | + | ||||
| 349 | +A required leading bound is: | ||||
| 350 | + | ||||
| 351 | +```text | ||||
| 352 | +||pilot_r - theta_hat_N|| | ||||
| 353 | + = O_p( m^(-r) + 1/(m sqrt(K)) + N^(-1) ). | ||||
| 354 | +``` | ||||
| 355 | + | ||||
| 356 | +Do not claim this bound if its proof fails for a considered model. | ||||
| 357 | + | ||||
| 358 | +### 6.2 Numerical conditioning and high-order weights | ||||
| 359 | + | ||||
| 360 | +Study weight explosion, conditioning of Vandermonde systems, finite precision error, and variance inflation as `r` grows. Evaluate partition patterns including `s={1,2,4,...}` and less aggressive alternatives, integer divisibility issues, and Richardson-like extrapolation with uneven sub-blocks. Optimize the choice of `s_j` under a prescribed variance-inflation or computation budget, if possible. | ||||
| 361 | + | ||||
| 362 | +Derive exact or bounded covariance between nested MLEs where tractable. Test coefficient condition numbers and the effective sample size of high-order corrected estimators. | ||||
| 363 | + | ||||
| 364 | +### 6.3 Order selection | ||||
| 365 | + | ||||
| 366 | +Explore a **data-adaptive choice of local bias order `r`**, but do not assert that choosing `r` from the data preserves the fixed-order theorem. If selection changes the estimator's asymptotic distribution, provide sample-splitting, independent pilot selection, uniform stochastic bounds, or an honest restricted claim. Treat the adaptive theory as an open research target until proved. | ||||
| 367 | + | ||||
| 368 | +**Gate 3:** derive weights from the linear system programmatically, verify moment constraints, and present a formal theorem plus numerical conditioning analysis. | ||||
| 369 | + | ||||
| 370 | +--- | ||||
| 371 | + | ||||
| 372 | +## 7. PHASE 4 — Prove the statistical–synchronization frontier | ||||
| 373 | + | ||||
| 374 | +### 7.1 Core general theorem (candidate) | ||||
| 375 | + | ||||
| 376 | +Let `r >= 1` be the effective local residual bias order and `q >= 0` be the number of globally aggregated Newton corrections. With fixed `r`, `q` and controlled constants, and with the pilot bound from Phase 3, derive a sufficient regime: | ||||
| 377 | + | ||||
| 378 | +```text | ||||
| 379 | +K = o( N^[ 1 - 1 / ( 2^(q+1) * r ) ] ). | ||||
| 380 | +``` | ||||
| 381 | + | ||||
| 382 | +The derivation should state explicitly how repeated quadratic convergence acts on BOTH: | ||||
| 383 | + | ||||
| 384 | +- deterministic bias `m^{-r}`; | ||||
| 385 | +- stochastic remainder `1/(m sqrt(K))`; | ||||
| 386 | +- global remainder `N^{-1}`. | ||||
| 387 | + | ||||
| 388 | +Show exactly when the bias restriction is dominant. Do not hide alternative restrictions that arise from nuisance parameters, approximation error, numerical tolerance, increasing dimension or nonuniform constants. | ||||
| 389 | + | ||||
| 390 | +### 7.2 Strengthening the contribution | ||||
| 391 | + | ||||
| 392 | +Go beyond a sufficient exponent. Investigate at least THREE of the following, with proofs if feasible: | ||||
| 393 | + | ||||
| 394 | +**A. Boundary distributions.** For `K ~ c N^alpha`, obtain centered or shifted limiting distributions, including explicit leading bias constants, for several nontrivial likelihood models. | ||||
| 395 | + | ||||
| 396 | +**B. Necessity / sharpness for a specified estimator family.** Construct examples showing the exponent cannot be relaxed *for the particular fixed `(r,q)` construction*, even though other estimators may do better. | ||||
| 397 | + | ||||
| 398 | +**C. Communication-aware decision theorem.** Given local fitting cost `T_fit(m,p)`, network latency `lambda`, bandwidth `B`, derivative transfer size and correction depth, characterize conditions under which `(r+1, q)` beats `(r, q+1)` in elapsed time at equal asymptotic precision. | ||||
| 399 | + | ||||
| 400 | +**D. Adaptive frontier.** Derive an oracle or regret-style bound for choosing `(r,q)` from pilot measurements, controlling selection-induced statistical error and network uncertainty. | ||||
| 401 | + | ||||
| 402 | +**E. Heterogeneous partitions.** Extend to unequal `m_k` and weighted aggregation, showing how bias corrections and local information geometry must change. | ||||
| 403 | + | ||||
| 404 | +**F. Robustness to model misspecification.** Establish asymptotic equivalence to centralized pseudo-MLE with sandwich covariance under defensible conditions, and distinguish this from Fisher-efficiency claims. | ||||
| 405 | + | ||||
| 406 | +**G. Approximate derivatives.** Bound how Hessian approximation, quantization, compression, inexact linear solves, or straggler failures perturb first-order equivalence. | ||||
| 407 | + | ||||
| 408 | +**H. Increasing dimension.** If realistic, derive explicit `p_N` dependencies in remainder and Hessian bounds. Do not relabel a fixed-`p` theorem as a high-dimensional theorem. | ||||
| 409 | + | ||||
| 410 | +### 7.3 Proof depth requirement | ||||
| 411 | + | ||||
| 412 | +Every theorem must have: | ||||
| 413 | + | ||||
| 414 | +- a complete statement and correctly scoped assumptions; | ||||
| 415 | +- an informative lemma sequence; | ||||
| 416 | +- no magical `o_p(1)` steps; | ||||
| 417 | +- all triangular-array / uniformity issues handled; | ||||
| 418 | +- moment and bias constants traced through the proof; | ||||
| 419 | +- a discussion of necessity versus sufficiency; | ||||
| 420 | +- a counterexample or violation for at least one essential assumption; | ||||
| 421 | +- a direct comparison with the closest prior theorem. | ||||
| 422 | + | ||||
| 423 | +**Gate 4:** at least one nontrivial theorem beyond a rephrasing of known one-step-plus-jackknife results is fully proved, **or** the report explicitly concludes that novelty is not yet proved and reframes the paper around validated insights and counterexamples. | ||||
| 424 | + | ||||
| 425 | +--- | ||||
| 426 | + | ||||
| 427 | +## 8. PHASE 5 — Exact analytic models and sharp counterexamples | ||||
| 428 | + | ||||
| 429 | +### 8.1 Exponential(rate) benchmark: full analytic treatment | ||||
| 430 | + | ||||
| 431 | +Prove using Gamma moments: | ||||
| 432 | + | ||||
| 433 | +```text | ||||
| 434 | +E[1 / Xbar_n], Var[1 / Xbar_n], | ||||
| 435 | +E[local jack2], Var[local jack2], | ||||
| 436 | +E[local jack3] (if integrability allows), | ||||
| 437 | +exact Newton identity, | ||||
| 438 | +finite-sample error identities where possible, | ||||
| 439 | +boundary distribution constants. | ||||
| 440 | +``` | ||||
| 441 | + | ||||
| 442 | +Derive from the gamma density rather than just reporting formulas. Check the exact conditions on `m` needed for moments to exist; distinguish bias existence, variance existence and higher-order integrability. Verify that the `jack3` formula yields feasible positive-rate estimates often enough for Newton and document when it does not. | ||||
| 443 | + | ||||
| 444 | +### 8.2 At least two additional nonlinear likelihoods | ||||
| 445 | + | ||||
| 446 | +Try and prioritize: | ||||
| 447 | + | ||||
| 448 | +1. Logistic regression with controlled predictors and nonseparation; include `p > 1`, conditioning, Newton numerical stability and exact/approximate centralized solutions. | ||||
| 449 | +2. Gamma GLM, Poisson regression, negative binomial regression, Weibull survival, or beta regression where likelihood nonlinearity makes bias correction meaningful. | ||||
| 450 | +3. A heteroskedastic nonlinear regression or simple volatility likelihood (e.g. GARCH) as a challenging extension, with dependence theory kept separate. | ||||
| 451 | + | ||||
| 452 | +For each: | ||||
| 453 | + | ||||
| 454 | +- write the log-likelihood, score and observed Hessian; | ||||
| 455 | +- specify data generating process and identification; | ||||
| 456 | +- establish which assumptions are theoretically justified versus numerically plausible; | ||||
| 457 | +- seek an explicit second-order bias coefficient, exact finite-sample identity, or asymptotic counterexample; | ||||
| 458 | +- report failures, singularities, boundary fits and weak identification; | ||||
| 459 | +- include a case where jackknife+Newton loses to another method. | ||||
| 460 | + | ||||
| 461 | +### 8.3 Adversarial configurations | ||||
| 462 | + | ||||
| 463 | +Build an explicit failure gallery: | ||||
| 464 | + | ||||
| 465 | +- `m` too small for a local MLE to exist; | ||||
| 466 | +- nearly singular information matrices; | ||||
| 467 | +- distributed covariate shift / non-i.i.d. local partitioning; | ||||
| 468 | +- outlier contamination and model misspecification; | ||||
| 469 | +- large `p/m` and separation; | ||||
| 470 | +- Hessian inexactness / quantization; | ||||
| 471 | +- jackknife noise amplification at high order; | ||||
| 472 | +- extreme network latency or slowest-node bottlenecks. | ||||
| 473 | + | ||||
| 474 | +**Gate 5:** exact exponential results verified by symbolic algebra and independent numerical checks; at least two other likelihoods implemented, with honest assumptions. | ||||
| 475 | + | ||||
| 476 | +--- | ||||
| 477 | + | ||||
| 478 | +## 9. PHASE 6 — Implement a research-grade benchmark library | ||||
| 479 | + | ||||
| 480 | +### 9.1 Technology | ||||
| 481 | + | ||||
| 482 | +Preferred stack: Python 3.11+ with NumPy, SciPy, pandas, matplotlib and pytest, plus JAX/PyTorch if useful for verified automatic differentiation. Optional Rust/C++ numerical kernels and MPI/Ray/Dask for genuine distributed tests only when justified by the environment. Pin dependencies and exact versions. No hard requirement that a GPU be present. | ||||
| 483 | + | ||||
| 484 | +Suggested project tree (adapt to existing UQO layout): | ||||
| 485 | + | ||||
| 486 | +```text | ||||
| 487 | +WP28-distributed-mle/ | ||||
| 488 | +├── CLAUDE.md # copy/symlink this mandate, if appropriate | ||||
| 489 | +├── README.md | ||||
| 490 | +├── PHASE_STATUS.md | ||||
| 491 | +├── research_log.md | ||||
| 492 | +├── paper/ | ||||
| 493 | +│ ├── main.tex | ||||
| 494 | +│ ├── preamble.tex | ||||
| 495 | +│ ├── sections/ | ||||
| 496 | +│ ├── appendices/ | ||||
| 497 | +│ ├── references.bib | ||||
| 498 | +│ └── figures/ | ||||
| 499 | +├── literature/ | ||||
| 500 | +│ ├── PRIOR_ART_MATRIX.csv | ||||
| 501 | +│ └── PRIORITY_AND_GAP.md | ||||
| 502 | +├── theory/ | ||||
| 503 | +│ ├── THEOREM_AUDIT.md | ||||
| 504 | +│ ├── ASSUMPTIONS.md | ||||
| 505 | +│ ├── proofs_check.py | ||||
| 506 | +│ └── symbolic_checks.py | ||||
| 507 | +├── src/pamle/ | ||||
| 508 | +│ ├── likelihoods.py | ||||
| 509 | +│ ├── local_fit.py | ||||
| 510 | +│ ├── partitioning.py | ||||
| 511 | +│ ├── jackknife.py | ||||
| 512 | +│ ├── derivatives.py | ||||
| 513 | +│ ├── algorithms.py | ||||
| 514 | +│ ├── aggregation.py | ||||
| 515 | +│ ├── communication.py | ||||
| 516 | +│ ├── diagnostics.py | ||||
| 517 | +│ └── runtime.py | ||||
| 518 | +├── experiments/ | ||||
| 519 | +│ ├── configs/ | ||||
| 520 | +│ ├── run_monte_carlo.py | ||||
| 521 | +│ ├── run_benchmarks.py | ||||
| 522 | +│ ├── run_ablations.py | ||||
| 523 | +│ └── EXPERIMENT_MANIFEST.csv | ||||
| 524 | +├── tests/ | ||||
| 525 | +│ ├── test_math_identities.py | ||||
| 526 | +│ ├── test_jackknife_weights.py | ||||
| 527 | +│ ├── test_models_and_gradients.py | ||||
| 528 | +│ ├── test_estimators.py | ||||
| 529 | +│ ├── test_asymptotic_rates.py | ||||
| 530 | +│ ├── test_communication_accounting.py | ||||
| 531 | +│ └── test_reproducibility.py | ||||
| 532 | +├── data/ # synthetic outputs + explicitly permitted data | ||||
| 533 | +├── results/ | ||||
| 534 | +│ ├── raw/ | ||||
| 535 | +│ ├── processed/ | ||||
| 536 | +│ ├── tables/ | ||||
| 537 | +│ ├── figures/ | ||||
| 538 | +│ └── resource_profiles/ | ||||
| 539 | +├── scripts/ | ||||
| 540 | +│ ├── setup.sh | ||||
| 541 | +│ ├── reproduce_all.sh | ||||
| 542 | +│ ├── compile_paper.sh | ||||
| 543 | +│ └── validate_pdf.sh | ||||
| 544 | +├── LIMITATIONS_AND_CLAIMS.md | ||||
| 545 | +├── FINAL_REVIEW.md | ||||
| 546 | +└── FINAL_DELIVERY.md | ||||
| 547 | +``` | ||||
| 548 | + | ||||
| 549 | +### 9.2 Mandatory estimator implementations | ||||
| 550 | + | ||||
| 551 | +Implement clean, common-interface versions of: | ||||
| 552 | + | ||||
| 553 | +- Full centralized maximum likelihood, using a trusted optimizer and tight tolerances. | ||||
| 554 | +- Average of independently fitted local MLEs. | ||||
| 555 | +- Average local MLE + **one** global Newton correction. | ||||
| 556 | +- Average local MLE + **two** global Newton corrections. | ||||
| 557 | +- Half-block jackknife initial estimator, without global correction. | ||||
| 558 | +- Half-block jackknife + **one** global Newton correction. | ||||
| 559 | +- Higher-order (quarter-block) jackknife, without global correction. | ||||
| 560 | +- Higher-order jackknife + **one** global Newton correction. | ||||
| 561 | +- Generalized `r`-th order split estimator + `q` global corrections. | ||||
| 562 | +- Credible implementations of at least two strong literature baselines where practical, such as surrogate likelihood/CSL and another relevant distributed estimator. If an exact faithful implementation is infeasible, identify the limitation and do not use a misnamed approximation. | ||||
| 563 | +- Optional bias-corrected local information-weighted averaging and adaptive method if justified by theory. | ||||
| 564 | + | ||||
| 565 | +### 9.3 Correctness before optimization | ||||
| 566 | + | ||||
| 567 | +- Unit tests: scalar and multivariate gradients/Hessians against high-accuracy finite differences and/or independent autodiff. | ||||
| 568 | +- Test the jackknife weights satisfy their moment equations up to floating-point tolerance. | ||||
| 569 | +- Test worker repartitioning, deterministic seeds, missing partitions, small `m`, singular Hessians and parameters near boundaries. | ||||
| 570 | +- For exponential likelihood, test exact Gamma moments and exact Newton identity over numerous random inputs. | ||||
| 571 | +- For logit, guard against separation, singularity and ill-conditioned curvature; distinguish exact MLE from ridge-penalized substitute. | ||||
| 572 | +- Check all algorithms agree with the centralized solution to specified tolerance when theory predicts it. | ||||
| 573 | +- Ensure `np.linalg.inv` is NOT used for production Newton steps. Use `solve`, regularization if reported, and diagnostics. | ||||
| 574 | +- Track optimization failures rather than discard failed replications silently. | ||||
| 575 | +- Capture and report both estimator validity and computational success rate. | ||||
| 576 | +- If implementing damped Newton or projection for robustness, distinguish its theoretical algorithm from the idealized undamped formula. | ||||
| 577 | + | ||||
| 578 | +**Gate 6:** all critical tests pass and the code reconstructs original-paper figures within stated tolerances before large experiments begin. | ||||
| 579 | + | ||||
| 580 | +--- | ||||
| 581 | + | ||||
| 582 | +## 10. PHASE 7 — Statistical Monte Carlo: exhaustive design, not a decorative chart | ||||
| 583 | + | ||||
| 584 | +### 10.1 Design matrix | ||||
| 585 | + | ||||
| 586 | +Run a factorial/sequential design covering: | ||||
| 587 | + | ||||
| 588 | +- `N`: logarithmic sequence spanning small, moderate and large sample sizes, chosen based on available RAM/compute; at least four distinct `N` values in the main rate study. | ||||
| 589 | +- `K`: logarithmic grid including values below, near and above `N^(1/2)`, `N^(3/4)`, `N^(7/8)`, `N^(11/12)` when integer block sizes and computation permit. | ||||
| 590 | +- `m`: explicitly report local sample sizes; do not quote exponents when the corresponding `m` fails to grow. | ||||
| 591 | +- `p`: small scalar case, moderate `p`, and a stress test for `p/m` approaching a problematic regime. | ||||
| 592 | +- Models: exponential(rate), logistic regression, plus at least one additional regular nonlinear likelihood. | ||||
| 593 | +- DGP conditions: well specified, misspecified (clearly labeled), varying Fisher condition numbers, balanced and deliberately skewed partitioning. | ||||
| 594 | +- Correction methods: raw averaging, one-/two-step Newton, jack2, jack3, and new method if supported. | ||||
| 595 | +- Network budgets: ideal communication-free statistical experiment, high-latency/low-bandwidth emulation, actual distributed test when possible. | ||||
| 596 | +- Repetitions: target at least 1,000 per **main statistical design** where practical; adaptively allocate computation and report actual replications and Monte Carlo standard errors. Do not confuse this target with previously executed 500-replication pilot. | ||||
| 597 | + | ||||
| 598 | +### 10.2 Required metrics | ||||
| 599 | + | ||||
| 600 | +Measure all of the following, as applicable: | ||||
| 601 | + | ||||
| 602 | +```text | ||||
| 603 | +bias, standard deviation, MSE, RMSE, | ||||
| 604 | +N-scaled and sqrt(N)-scaled errors vs theta_0, | ||||
| 605 | +sqrt(N)-scaled estimator gap vs centralized MLE, | ||||
| 606 | +coverage and length of 90%, 95%, 99% confidence intervals, | ||||
| 607 | +condition number, Newton residual norm, convergence rate, | ||||
| 608 | +optimization failure / nonexistence / infeasible parameter rate, | ||||
| 609 | +realized worker fits, actual floating-point runtime, memory, | ||||
| 610 | +communication rounds, downlink + uplink bytes, p50/p90/p99 latency, | ||||
| 611 | +energy if actually measured and instrumented. | ||||
| 612 | +``` | ||||
| 613 | + | ||||
| 614 | +Use paired replications where comparing estimators: same synthetic sample or sufficient statistics, same split, same DGP and random stream across methods. Publish Monte Carlo standard errors or confidence bands and record simulation seeds. | ||||
| 615 | + | ||||
| 616 | +### 10.3 Statistical diagnostics | ||||
| 617 | + | ||||
| 618 | +- Plot `log RMSE` against `log N` and investigate observed slopes; compare with theoretical slopes only when regimes are sufficiently large. | ||||
| 619 | +- Plot scaled estimator gaps as a function of `K/N^alpha`, not only raw `K`. | ||||
| 620 | +- Verify exact boundary-shift constants in exponential likelihood using several `c` values and increasing `N`. | ||||
| 621 | +- Plot model-specific bias–variance tradeoffs for jackknife correction order. | ||||
| 622 | +- For interval inference, compare nominal versus empirical coverage and uncertainty estimator consistency. | ||||
| 623 | +- Run sensitivity analyses for unusually large jackknife weights, nonlinear curvature and near-boundary estimates. | ||||
| 624 | +- Label every figure with the estimation procedure, DGP, sample size, number of partitions, replication count, units and uncertainty quantification. | ||||
| 625 | +- Report finite-sample failures rather than condition on the subset of successful trials without noting selection. | ||||
| 626 | +- No fabricated or manually inserted results. All paper numbers and figures must be regenerated from committed CSV/Parquet outputs. | ||||
| 627 | + | ||||
| 628 | +### 10.4 Reproducibility manifest | ||||
| 629 | + | ||||
| 630 | +For each completed run write: | ||||
| 631 | + | ||||
| 632 | +```text | ||||
| 633 | +run_id,git_commit,python_version,dependency_lock_sha256, | ||||
| 634 | +seed,N,K,m,p,DGP,method,optimizer,tolerance,replicates, | ||||
| 635 | +parallel_backend,node_count,hardware,OS,wall_seconds, | ||||
| 636 | +communicated_bytes,rounds,status,raw_output_sha256 | ||||
| 637 | +``` | ||||
| 638 | + | ||||
| 639 | +**Gate 7:** full tables exist, figures directly follow data, and results do not claim asymptotic behavior unsupported by the tested regime. | ||||
| 640 | + | ||||
| 641 | +--- | ||||
| 642 | + | ||||
| 643 | +## 11. PHASE 8 — REAL communication and compute benchmarks | ||||
| 644 | + | ||||
| 645 | +Do not call an in-memory mathematical partition a distributed cluster benchmark. Execute independent workers/processes or actual machines, record network traffic and synchronization overhead, and include an empirical systems section only if there is genuine evidence. | ||||
| 646 | + | ||||
| 647 | +### 11.1 Benchmark architecture | ||||
| 648 | + | ||||
| 649 | +Implement a coordinator/worker protocol with explicit events: | ||||
| 650 | + | ||||
| 651 | +```text | ||||
| 652 | +Stage A workers fit local MLE / split MLEs in parallel; | ||||
| 653 | +Stage B workers send corrected local parameter vectors; | ||||
| 654 | +Stage C coordinator aggregates and broadcasts theta^(0); | ||||
| 655 | +Stage D workers evaluate score + Hessian at global theta^(0); | ||||
| 656 | +Stage E workers send derivatives; | ||||
| 657 | +Stage F coordinator aggregates derivatives and solves Newton system; | ||||
| 658 | +Stage G additional correction steps repeat D-F, if requested. | ||||
| 659 | +``` | ||||
| 660 | + | ||||
| 661 | +Account for every broadcast, parameter vector, gradient vector, Hessian, message header, serialization cost, worker startup, scheduler delay, data movement and retry. Distinguish *network message count*, *communication rounds*, *transferred floating-point values* and *actual byte totals*. Specify the communication model: star coordinator vs all-reduce vs decentralized. For dense second derivatives, expect `O(K p^2)` uplink numeric payloads per correction, with additional downlink payloads and overhead. | ||||
| 662 | + | ||||
| 663 | +### 11.2 Hardware scope | ||||
| 664 | + | ||||
| 665 | +The researcher may have access to a MacLustr collection of Mac Studio / Mac mini nodes and other compute. **Inventory live, permitted resources**, do not hard-code model counts from stale descriptions. If available, benchmark up to available levels such as 1, 2, 4, 8 and 16 workers and more only when practical. If not available, perform a verified single-host multi-process baseline and clearly state its limits. | ||||
| 666 | + | ||||
| 667 | +Capture: | ||||
| 668 | + | ||||
| 669 | +- processor/model, CPU architecture, number of cores, RAM, accelerator availability; | ||||
| 670 | +- OS, BLAS backend, Python/library versions; | ||||
| 671 | +- network interface/link rate, observed bandwidth, latency and topology; | ||||
| 672 | +- worker startup and orchestration overhead; | ||||
| 673 | +- local-fit time distribution and straggler delay; | ||||
| 674 | +- derivative compute time and Hessian solve time; | ||||
| 675 | +- coordinator CPU/RAM burden; | ||||
| 676 | +- speedup, parallel efficiency and resource utilization; | ||||
| 677 | +- where measured, electricity and dollar-cost assumptions. | ||||
| 678 | + | ||||
| 679 | +### 11.3 The economics of synchronization | ||||
| 680 | + | ||||
| 681 | +Derive and empirically calibrate a cost model, such as: | ||||
| 682 | + | ||||
| 683 | +```text | ||||
| 684 | +T_total(r,q,K,p,N) | ||||
| 685 | + = T_local(r, N/K, p, worker_resources) | ||||
| 686 | + + T_schedule(K) | ||||
| 687 | + + T_aggregate_pilot(K,p) | ||||
| 688 | + + q*[T_broadcast(K,p) + T_derivatives(N/K,p) | ||||
| 689 | + + T_collect(K,p^2) + T_linear_solve(p)] | ||||
| 690 | + + T_stragglers(K) + T_failures(K). | ||||
| 691 | +``` | ||||
| 692 | + | ||||
| 693 | +Treat this as a **proposed model**, not a proved identity. Measure the terms. Model overlapping compute/communication and asynchronous variants if supported, and distinguish sums from critical paths in parallel execution. | ||||
| 694 | + | ||||
| 695 | +Study the crossover at equal statistical accuracy: | ||||
| 696 | + | ||||
| 697 | +- jack2 + 1 global step versus ordinary pilot + 2 global steps; | ||||
| 698 | +- jack3 + 1 global step versus jack2 + more rounds; | ||||
| 699 | +- exact/sufficient-statistic pooling, where applicable; | ||||
| 700 | +- CSL/surrogate likelihood and other strong baselines; | ||||
| 701 | +- dense Hessian communication versus Hessian-vector products or approximate derivatives. | ||||
| 702 | + | ||||
| 703 | +Derive a decision boundary involving latency, bandwidth, worker compute speed, `m`, and `p`. If it is empirical rather than general, call it empirical. | ||||
| 704 | + | ||||
| 705 | +### 11.4 Acknowledge benchmark limitations | ||||
| 706 | + | ||||
| 707 | +- Single-host processes do not validate cross-machine network scaling. | ||||
| 708 | +- Local wall-clock speedups do not imply total cost benefits. | ||||
| 709 | +- `K` partitions need not equal `K` physical hosts. | ||||
| 710 | +- Large `p` may make Hessian communication dominant; do not extrapolate scalar examples. | ||||
| 711 | +- Asynchronous updates change the mathematical estimator and may not inherit exact-theorem guarantees. | ||||
| 712 | + | ||||
| 713 | +**Gate 8:** any hardware claims have run logs, profiler measurements and manifests. Otherwise explicitly state that real distributed performance is not established. | ||||
| 714 | + | ||||
| 715 | +--- | ||||
| 716 | + | ||||
| 717 | +## 12. PHASE 9 — Stronger directions / actual discovery search | ||||
| 718 | + | ||||
| 719 | +Select the strongest viable research contribution based on proofs + novelty audit + experiments, rather than trying to force all directions into one unfocused manuscript. | ||||
| 720 | + | ||||
| 721 | +### Track A — Optimal local correction versus global synchronization | ||||
| 722 | + | ||||
| 723 | +Mathematically characterize when one extra local extrapolation stage replaces one global Newton synchronization, holding inferential accuracy fixed. Pursue sharp upper/lower bounds under a *specified* family of communication/computation models. Provide an experimentally calibrated phase diagram. | ||||
| 724 | + | ||||
| 725 | +### Track B — Adaptive bias order under latency constraints | ||||
| 726 | + | ||||
| 727 | +Design a runtime selection policy for `(r,q)` based on locally estimable bias, variance, Hessian conditioning and network cost. Prove nonpathological selection consistency, oracle-rate inequality or finite-sample dominance within a stated model, if achievable. Use valid independence/selection handling. | ||||
| 728 | + | ||||
| 729 | +### Track C — Statistically efficient inexact derivatives | ||||
| 730 | + | ||||
| 731 | +Study compressed or sketched Hessians/gradients. Characterize derivative error tolerances, e.g., sufficient `||delta_g||` and `||delta_H||` orders for first-order equivalent inference. Combine this with bias cancellation to reduce *bytes*, not just rounds. Establish all matrix perturbation steps. | ||||
| 732 | + | ||||
| 733 | +### Track D — Heterogeneous / federated econometrics | ||||
| 734 | + | ||||
| 735 | +Generalize the scheme to uneven worker counts, unequal sample sizes, covariate distribution shifts, model misspecification, and possibly overlapping samples; derive weighted bias corrections and robust variance. Prove exact scope rather than handwave a heterogeneous CLT. | ||||
| 736 | + | ||||
| 737 | +### Track E — Lower bounds, counterexamples and impossibility | ||||
| 738 | + | ||||
| 739 | +If speed/novelty claims do not survive scrutiny, identify an informative hard instance or impossibility for a given class of local-and-round-limited protocols; distinguish algorithm-family lower bounds from universal distributed estimation lower bounds. This can anchor a strong theory paper on its own. | ||||
| 740 | + | ||||
| 741 | +### Explicit selection rule | ||||
| 742 | + | ||||
| 743 | +At the end of this phase, record: | ||||
| 744 | + | ||||
| 745 | +```text | ||||
| 746 | +Primary theorem claim: | ||||
| 747 | +Nearest existing theorem(s): | ||||
| 748 | +Precise difference in assumptions/conclusion: | ||||
| 749 | +Complete proof available (Y/N): | ||||
| 750 | +Counterexample search completed (Y/N): | ||||
| 751 | +Numerical supporting evidence available (Y/N): | ||||
| 752 | +Communication benefit established (mathematical/empirical/neither): | ||||
| 753 | +Retain, weaken, replace, or drop: | ||||
| 754 | +``` | ||||
| 755 | + | ||||
| 756 | +**Gate 9:** one coherent article thesis, not six unrelated novelty claims. | ||||
| 757 | + | ||||
| 758 | +--- | ||||
| 759 | + | ||||
| 760 | +## 13. PHASE 10 — Write the paper as a serious journal submission | ||||
| 761 | + | ||||
| 762 | +### 13.1 Mandatory manuscript structure | ||||
| 763 | + | ||||
| 764 | +Adapt chapter allocation to findings; recommended: | ||||
| 765 | + | ||||
| 766 | +1. **Introduction.** The problem, economic/statistical motivation, exact literature gap, clearly delimited contributions, and why the tradeoff matters. | ||||
| 767 | +2. **Related literature.** A substantive, fair comparison of one-shot and multi-round distributed MLE, bias correction, surrogate likelihood and communication-limited inference. | ||||
| 768 | +3. **Econometric environment and distributed protocol.** Likelihood, partitions, assumptions, local estimators, messages, computational model. | ||||
| 769 | +4. **General bias-correction construction.** Weight system, common influence preservation, variance cost, numerical conditioning. | ||||
| 770 | +5. **Main theoretical results.** Theorem statements, interpretation, sufficient/frontier regimes, proof sketch with complete appendix. | ||||
| 771 | +6. **Exact models and boundaries.** Exponential exact identities and nontrivial nonlinear examples, including failure regimes. | ||||
| 772 | +7. **Computation–communication frontier.** Model, tradeoff theorems or conditional predictions, protocol comparison. | ||||
| 773 | +8. **Monte Carlo evidence.** Complete design, replication count, Monte Carlo uncertainty, bias/MSE/coverage/failure tables and figures. | ||||
| 774 | +9. **Real distributed benchmarks (only if actually run).** Hardware, environment, transfer accounting, elapsed-time and crossover analysis. | ||||
| 775 | +10. **Robustness / extensions.** Misspecification, heterogeneous partitions, inexact Hessians, high dimension or dependency as appropriately substantiated. | ||||
| 776 | +11. **Discussion and limitations.** Known methods, non-novel pieces, remaining open issues, domain restrictions. | ||||
| 777 | +12. **Conclusion.** Short, proportional to evidence, no marketing language. | ||||
| 778 | +13. **References.** Verified, machine-readable metadata. | ||||
| 779 | +14. **Technical appendices.** Every proof, asymptotic expansion, supplementary models, algorithms, additional sensitivity tables, replication instructions. | ||||
| 780 | + | ||||
| 781 | +### 13.2 Writing quality and tone | ||||
| 782 | + | ||||
| 783 | +Write in precise, natural, restrained academic English (top econometrics / theoretical statistics style). Avoid generic AI prose and unsupported superlatives: “groundbreaking,” “revolutionary,” “paradigm shift,” “legendary,” “remarkable,” “unprecedented,” “significantly better” without formal statistical support. Favor concise argumentation, strong results, intuitive transitions and properly qualified claims. | ||||
| 784 | + | ||||
| 785 | +- State exactly what is new versus already known. | ||||
| 786 | +- Make propositions, lemmas, theorems, assumptions, definitions, remarks and corollaries internally consistent. | ||||
| 787 | +- Use stable notation `N, K, m, p, r, q` throughout. | ||||
| 788 | +- Clearly distinguish *inference equivalence* to a centralized estimator from *optimality* or *exact equality*. | ||||
| 789 | +- Place technical rates and conditions adjacent to the statements they qualify. | ||||
| 790 | +- Treat normal confidence intervals as requiring a valid variance estimator; mere point-estimator convergence is not enough to claim valid coverage. | ||||
| 791 | +- Tables and plots must have units, populations, seeds/replicates when relevant, and intelligible notes. | ||||
| 792 | +- Do not claim runtime improvements based on FLOP counts without actual measurement or justified analytic model. | ||||
| 793 | +- Do not cite a source for a theorem it does not actually establish. | ||||
| 794 | + | ||||
| 795 | +### 13.3 Authorship, affiliations and funding | ||||
| 796 | + | ||||
| 797 | +Working manuscript attribution should preserve: | ||||
| 798 | + | ||||
| 799 | +```text | ||||
| 800 | +Simon-Pierre Boucher | ||||
| 801 | +Université du Québec en Outaouais | ||||
| 802 | + | ||||
| 803 | +GPT-6.1 | ||||
| 804 | +AI contribution / provenance of prior theoretical draft | ||||
| 805 | +``` | ||||
| 806 | + | ||||
| 807 | +If the existing UQO research series has a formal metadata / disclosure template, comply with that template and document any change to author display. The journal submission version may need GPT-6.1 removed from the formal author list and placed in transparent AI-use disclosure; **flag this for the human author rather than concealing the difference**. Never invent a model email address, institutional affiliation or ORCID. | ||||
| 808 | + | ||||
| 809 | +Research program funding line to include **only if confirmed for this particular WP28 project**: | ||||
| 810 | + | ||||
| 811 | +> Research funded by the FIRC (Fonds institutionnel de recherche et de création), Université du Québec en Outaouais. | ||||
| 812 | + | ||||
| 813 | +Because this line has been used for other UQO working papers, verify that its use on WP28 is appropriate rather than automatically claiming funding. | ||||
| 814 | + | ||||
| 815 | +### 13.4 Style / LaTeX quality | ||||
| 816 | + | ||||
| 817 | +- Follow native UQO working-paper style if one exists. Otherwise use a clean, sophisticated, predominantly white journal design with readable text and restrained accent color; no dark cover or promotional brochure aesthetics. | ||||
| 818 | +- 11pt or similarly comfortable font; professional math typesetting; linked PDF contents, hyperlinked references, booktabs tables, float control, clever cross-references and consistent equation numbering. | ||||
| 819 | +- Use `amsmath`, `amsthm`, `mathtools`, `booktabs`, `microtype`, `hyperref`, `cleveref`, `natbib`/`biblatex` as appropriate and available. | ||||
| 820 | +- Prefer vector figures (PDF/SVG converted properly) and generated TikZ for simple diagrams; no rasterized text. | ||||
| 821 | +- Centralize macros and theorem styles in the preamble; compile without undefined references or citations. | ||||
| 822 | +- Make the title page include WP28, date, authors, affiliations/disclosure, abstract, keywords and JEL codes (`C13`, `C15`, `C55`, `C63` subject to fit). | ||||
| 823 | +- Include algorithm pseudocode that accurately reflects communications and synchronized derivative evaluations. | ||||
| 824 | +- Check all math fits the page; no overfull/underfull warnings that materially harm appearance. | ||||
| 825 | +- Do not artificially inflate the page count. | ||||
| 826 | + | ||||
| 827 | +### 13.5 Bibliography rules | ||||
| 828 | + | ||||
| 829 | +- Source all bibliographic entries from verifiable journal DOI or publisher pages, supplemented by preprint dates where needed. | ||||
| 830 | +- Verify author order, title spelling, publication year, volume, pages and DOI. | ||||
| 831 | +- Do not cite unpublished manuscripts as peer-reviewed unless they actually are. | ||||
| 832 | +- Use primary papers for technical claims and compare the exact theorem statement/assumption set. | ||||
| 833 | +- Cite priority-threatening work prominently, not buried in generic related work. | ||||
| 834 | +- Include only works genuinely read and relevant; retain a wider research bibliography separately if helpful. | ||||
| 835 | + | ||||
| 836 | +**Gate 10:** complete meaningful article, full appendix, linked tables/figures, a coherent and verified novelty claim, and no unsupported quantitative assertions. | ||||
| 837 | + | ||||
| 838 | +--- | ||||
| 839 | + | ||||
| 840 | +## 14. PHASE 11 — Adversarial referee and proof audit | ||||
| 841 | + | ||||
| 842 | +Simulate at least three independent review perspectives; log objections and responses: | ||||
| 843 | + | ||||
| 844 | +**Referee A: theoretical econometrician.** Challenges stochastic expansions, uniformity, bias cancellation, influence-function equivalence, Fisher/sandwich covariance, CLT, conditioning, and necessity of rate restrictions. | ||||
| 845 | + | ||||
| 846 | +**Referee B: statistical optimization specialist.** Challenges novelty versus Huang–Huo, Zhang–Duchi–Wainwright, CSL and known higher-order expansions; examines Hessian solves, alternative algorithms, strength of numerical baseline and edge cases. | ||||
| 847 | + | ||||
| 848 | +**Referee C: distributed-systems/reproducibility specialist.** Challenges synchronization definitions, true worker independence, network accounting, memory, speedups, end-to-end experiments, stragglers and raw-data reproducibility. | ||||
| 849 | + | ||||
| 850 | +For every objection, respond with (a) exact location in paper/code, (b) correction made, (c) new proof/test if needed, and (d) residual limitation. Record unresolved issues candidly; do not have the same model merely declare its own work accepted. | ||||
| 851 | + | ||||
| 852 | +### Formal audit checklist | ||||
| 853 | + | ||||
| 854 | +- Every theorem's assumptions are enumerated. | ||||
| 855 | +- No proof relies on an unproved stronger bound in disguise. | ||||
| 856 | +- Expansions used under local sample size `m/2` or `m/4` are valid for the stated `m` range. | ||||
| 857 | +- `K=o(N^alpha)` is always interpreted as a triangular-array rate, not a fixed-N machine limit. | ||||
| 858 | +- Boundary constants have been independently checked. | ||||
| 859 | +- Every table value has a traceable input/output path. | ||||
| 860 | +- New method comparisons include ordinary local averaging + two Newton rounds. | ||||
| 861 | +- A baseline with exact sufficient-statistic aggregation is shown for applicable families. | ||||
| 862 | +- Communication savings distinguish actual bytes and rounds. | ||||
| 863 | +- The paper openly states if zero new theorem or no actual cluster benchmarks were achieved. | ||||
| 864 | +- AI contribution disclosure and human review requirements are explicit. | ||||
| 865 | +- Paper/source sync passes and all PDF page elements render cleanly. | ||||
| 866 | + | ||||
| 867 | +**Gate 11:** produce `FINAL_REVIEW.md` with a final verdict `ready for human review / theoretically incomplete / novelty unresolved / computational evidence insufficient`, plus actionable issues ranked by severity. | ||||
| 868 | + | ||||
| 869 | +--- | ||||
| 870 | + | ||||
| 871 | +## 15. PHASE 12 — Final build, packaging, and delivery | ||||
| 872 | + | ||||
| 873 | +### 15.1 Build and verification | ||||
| 874 | + | ||||
| 875 | +Provide an executable workflow, ideally: | ||||
| 876 | + | ||||
| 877 | +```bash | ||||
| 878 | +python -m pip install -r requirements.txt | ||||
| 879 | +pytest -q | ||||
| 880 | +python experiments/run_monte_carlo.py --config experiments/configs/reproduce_main.yaml | ||||
| 881 | +python experiments/run_benchmarks.py --config experiments/configs/main.yaml # only when permitted | ||||
| 882 | +bash scripts/compile_paper.sh | ||||
| 883 | +bash scripts/validate_pdf.sh | ||||
| 884 | +``` | ||||
| 885 | + | ||||
| 886 | +Update commands to match reality. Do not add fake scripts or claim benchmark success when the environment cannot execute them. | ||||
| 887 | + | ||||
| 888 | +Verify: | ||||
| 889 | + | ||||
| 890 | +- PDF actually exists, is nonempty, and its text is searchable. | ||||
| 891 | +- First page, sample theorem page, main table/figure pages and final appendix render correctly. | ||||
| 892 | +- No missing reference/citation/equation cross-reference, broken figure, clipped formula or watermark. | ||||
| 893 | +- Main tables are generated programmatically from data files. | ||||
| 894 | +- Source compiles on a clean environment or with clearly documented toolchain assumptions. | ||||
| 895 | +- Project checksums and commit state are captured. | ||||
| 896 | +- The article is named consistently with WP28, not WP27 or an unrelated previous series. | ||||
| 897 | + | ||||
| 898 | +### 15.2 Delivery artifact checklist | ||||
| 899 | + | ||||
| 900 | +At completion, create (adapt actual filenames to series conventions): | ||||
| 901 | + | ||||
| 902 | +```text | ||||
| 903 | +WP28_Distributed_MLE_Boucher.pdf | ||||
| 904 | +WP28_Distributed_MLE_Boucher.tex or paper/main.tex | ||||
| 905 | +WP28_Distributed_MLE_Source_and_Reproducibility.zip | ||||
| 906 | +WP28_Research_Summary.md | ||||
| 907 | +WP28_Theorem_Audit.md | ||||
| 908 | +WP28_Prior_Art_and_Novelty.md | ||||
| 909 | +WP28_Experiment_Results.csv | ||||
| 910 | +WP28_Final_Review.md | ||||
| 911 | +``` | ||||
| 912 | + | ||||
| 913 | +Give the researcher a closing report specifying: | ||||
| 914 | + | ||||
| 915 | +1. Full article title, exact authorship/disclosure representation, WP28 identifier and verified page count. | ||||
| 916 | +2. Strongest proved theorem, assumptions and exact rate/bound—not just intuition. | ||||
| 917 | +3. What is established as new versus known or not checked. | ||||
| 918 | +4. Number of simulations actually run, whether they completed, datasets, seed, uncertainty and code path. | ||||
| 919 | +5. Whether actual distributed compute benchmarks were performed, on which verified machines, and measured results. | ||||
| 920 | +6. Main caveats and unresolved mathematical/computational issues. | ||||
| 921 | +7. Exact paths to PDF, LaTeX, source archive, bibliography and output data. | ||||
| 922 | +8. Reproduction and compilation commands. | ||||
| 923 | +9. Suggested next proof or experiment that would most improve publishability. | ||||
| 924 | + | ||||
| 925 | +**Gate 12:** deliver a buildable manuscript and research artifacts in the actual repository. Do not end with a roadmap in place of results. | ||||
| 926 | + | ||||
| 927 | +--- | ||||
| 928 | + | ||||
| 929 | +## 16. Scientific acceptance standards: pass/fail rubric | ||||
| 930 | + | ||||
| 931 | +The project is **not complete** merely because a PDF compiles. Audit every category: | ||||
| 932 | + | ||||
| 933 | +| Category | Required evidence | Failure condition | | ||||
| 934 | +|---|---|---| | ||||
| 935 | +| Mathematical correctness | Full proofs, explicit assumptions, verified stochastic orders | Missing random remainder, unjustified asymptotics | | ||||
| 936 | +| Research contribution | Precise difference from closest literature and substantive new result or defensible negative discovery | Claim of novelty based only on jackknife+Newton combination | | ||||
| 937 | +| Econometric validity | Appropriate variance, coverage, fixed-`p` scope and misspecification warnings | Fisher efficiency claimed without correct model conditions | | ||||
| 938 | +| Algorithmic correctness | Unit tests, stable solves, failure handling, derivative checks | Unchecked Hessian inverses or silent fit failures | | ||||
| 939 | +| Statistical experiments | Raw results, seeds, uncertainty, proper baselines, honest N/K/m | Hypothetical speedup marketed as measured | | ||||
| 940 | +| Systems validation | Real messages and timing logs for any physical-cluster claims | Synthetic partitions passed off as multi-host deployment | | ||||
| 941 | +| Literature integrity | Verified DOI/metadata and theorem-level comparisons | Fabricated citations or priority omission | | ||||
| 942 | +| Manuscript quality | Complete argument, journal-style typography, clean figures | Decorative length, overclaiming, repetitive prose | | ||||
| 943 | +| Reproducibility | Pinned deps, scripts, results manifest, exact commands | Non-reconstructible reported numbers | | ||||
| 944 | +| Attribution | Simon-Pierre Boucher properly named; AI role transparently recorded | Invented AI credential/affiliation or hidden assistance | | ||||
| 945 | + | ||||
| 946 | +--- | ||||
| 947 | + | ||||
| 948 | +## 17. Mandatory mathematical appendix tasks (detailed proof queue) | ||||
| 949 | + | ||||
| 950 | +Complete or disprove these in order, and keep a numbered ledger. | ||||
| 951 | + | ||||
| 952 | +**Lemma 1 — Common influence preservation.** For each split granularity `s`, prove the average of the `s` disjoint block influence sums equals the original full-block influence sum. Extend to arbitrary normalized extrapolation weights. | ||||
| 953 | + | ||||
| 954 | +**Lemma 2 — High-order bias cancellation.** Solve the Vandermonde system and show corrected bias `O(m^{-r})`. State how unknown bias coefficients cancel under equal-distribution assumptions. | ||||
| 955 | + | ||||
| 956 | +**Lemma 3 — Local stochastic remainder.** Under uniform `L2` controls, show `E||R^J_{k,r}||^2 <= C_r/m^2`, with `C_r` depending explicitly on the weights and split sizes. | ||||
| 957 | + | ||||
| 958 | +**Lemma 4 — Averaged random remainder.** For independent blocks, prove the variance/second-moment inequality giving `O_p(1/(m sqrt K))` after centering. Do not assume nested within-worker fits are independent. | ||||
| 959 | + | ||||
| 960 | +**Lemma 5 — Central-MLE comparison.** Cancel the common global influence term and prove `O_p(m^{-r}+(m sqrt K)^{-1}+N^{-1})` relative to centralized MLE. | ||||
| 961 | + | ||||
| 962 | +**Lemma 6 — One-step Newton quadratic remainder.** Prove the integral identity and uniform Hessian bound on a path in the attraction region. | ||||
| 963 | + | ||||
| 964 | +**Lemma 7 — q-step propagation.** With fixed `q`, establish the repeated-squaring bound, including the randomness of the constant and consistency of intermediate iterates. | ||||
| 965 | + | ||||
| 966 | +**Theorem 1 — First-order equivalence.** Under the stated complete assumptions, derive a sufficient `K` rate and the resulting influence-function CLT / covariance. | ||||
| 967 | + | ||||
| 968 | +**Theorem 2 — Generic (r,q) frontier.** Prove the advertised sufficient exponent or replace it with the correct bound if supplementary terms dominate. | ||||
| 969 | + | ||||
| 970 | +**Theorem 3 — Exact exponential boundary.** Derive all Gamma moments needed and establish the nonzero limit `-4 theta_0 c^4` for half-block jackknife + one global Newton step when `K ~ c N^(7/8)`. | ||||
| 971 | + | ||||
| 972 | +**Theorem 4 — Distinct stronger contribution.** Prove an additional relevant result not simply implicit in the first three (e.g., adaptive crossover, byte/error bound, inexact Newton perturbation theorem, heterogeneity regime or constrained optimality result), subject to literature priority verification. | ||||
| 973 | + | ||||
| 974 | +**Proposition — Failure/counterexample.** Demonstrate a setting where higher-order correction harms MSE, invalidates parameter feasibility, or violates a theorem assumption. Make it useful for method selection. | ||||
| 975 | + | ||||
| 976 | +**Corollary — Inferential validity.** Specify the conditions under which confidence intervals using consistently estimated centralized Fisher/sandwich covariance remain valid for the distributed estimator. | ||||
| 977 | + | ||||
| 978 | +**Proof ledger** must contain: | ||||
| 979 | + | ||||
| 980 | +```text | ||||
| 981 | +statement_id | status | assumptions | source_or_new | proof_file | | ||||
| 982 | +independent_check | counterexample_attempt | paper_location | unresolved_issue | ||||
| 983 | +``` | ||||
| 984 | + | ||||
| 985 | +--- | ||||
| 986 | + | ||||
| 987 | +## 18. Mandatory experimental ablations and comparisons | ||||
| 988 | + | ||||
| 989 | +Every estimator comparison must control for both **statistics** and **resources**. At minimum: | ||||
| 990 | + | ||||
| 991 | +1. **Fixed total N, varying K:** how accuracy deteriorates as local sample sizes shrink. | ||||
| 992 | +2. **Fixed K, varying N:** whether empirical scaling agrees with asymptotic claims. | ||||
| 993 | +3. **Fixed communication rounds:** compare improved local corrections at same number of derivative synchronizations. | ||||
| 994 | +4. **Fixed computational budget:** compare ordinary and higher-order local fitting using elapsed time, not raw count of method names. | ||||
| 995 | +5. **Fixed target accuracy:** minimize wall-clock time subject to a common RMSE or inferential-coverage threshold. | ||||
| 996 | +6. **Fixed network bandwidth / latency:** vary local compute speed and evaluate synchronization crossover. | ||||
| 997 | +7. **Jackknife variance inflation:** compare error variance and failure rates across `r=1,2,3,4` as feasible. | ||||
| 998 | +8. **Global Newton rounds:** compare `q=0,1,2,3` and show when extra rounds dominate high-order bias cancellation. | ||||
| 999 | +9. **Hessian communication:** dense exact Hessian versus candidate approximations, with exact byte accounting and accuracy degradation. | ||||
| 1000 | +10. **Parameter dimension:** evaluate how `p` changes curvature, communication size and fitted sample requirements. | ||||
| 1001 | +11. **Imbalanced worker sizes:** equal versus unequal `m_k`, weighted versus naive aggregation. | ||||
| 1002 | +12. **Near-degenerate cases:** weak signal, almost singular Fisher information, separation, contamination, heavy tails and worker fit failures. | ||||
| 1003 | + | ||||
| 1004 | +A figure is mandatory only if backed by actual computed data. For any unattained experiment, document a precise blocker and do not fabricate a placeholder plot. | ||||
| 1005 | + | ||||
| 1006 | +--- | ||||
| 1007 | + | ||||
| 1008 | +## 19. Concrete prospective figure and table program | ||||
| 1009 | + | ||||
| 1010 | +### Figures | ||||
| 1011 | + | ||||
| 1012 | +- **Figure 1:** coordinator/worker protocol with exact uplink, downlink and synchronization stages. | ||||
| 1013 | +- **Figure 2:** theoretical admissible partition exponent `alpha(r,q)` and explicit caveat: sufficient rates only, fixed `r,q,p`. | ||||
| 1014 | +- **Figure 3:** exact Gamma-model boundary shift versus `c`, Monte Carlo intervals and analytic `-4 theta_0 c^4` curve. | ||||
| 1015 | +- **Figure 4:** RMSE and bias of raw, jack2, jack3, multi-round Newton vs `m`, emphasizing finite-sample variance amplification. | ||||
| 1016 | +- **Figure 5:** observed empirical probability of valid local fits and conditioning diagnostics. | ||||
| 1017 | +- **Figure 6:** measured real/simulated-with-clear-label communication-vs-computation phase diagram. | ||||
| 1018 | +- **Figure 7:** latency/bandwidth crossover map comparing jack2+1 with ordinary+2 under equal target accuracy. | ||||
| 1019 | +- **Figure 8:** actual multi-node speedup and parallel efficiency *only if measured*. | ||||
| 1020 | +- **Figure A1:** nontrivial likelihood counterexample illustrating limits of a general claim. | ||||
| 1021 | + | ||||
| 1022 | +### Tables | ||||
| 1023 | + | ||||
| 1024 | +- **Table 1:** literature/priority comparison with the closest relevant work. | ||||
| 1025 | +- **Table 2:** estimator definitions, local fit counts, global corrections, network phases, bytes and proved statistical regime. | ||||
| 1026 | +- **Table 3:** theorem assumptions and applicability by model class. | ||||
| 1027 | +- **Table 4:** Monte Carlo bias, SD, RMSE, coverage, solver failures and Monte Carlo standard errors. | ||||
| 1028 | +- **Table 5:** computational time and messages by worker count, machine class and network profile. | ||||
| 1029 | +- **Table 6:** ablation of order `r`, steps `q`, Hessian approximation and stability. | ||||
| 1030 | + | ||||
| 1031 | +Do not force a figure or table to exist if its substantive data or mathematical content is unavailable. Prioritize interpretability and exact replication. | ||||
| 1032 | + | ||||
| 1033 | +--- | ||||
| 1034 | + | ||||
| 1035 | +## 20. Autonomy and phase continuation protocol | ||||
| 1036 | + | ||||
| 1037 | +After completing each phase, append to `PHASE_STATUS.md`: | ||||
| 1038 | + | ||||
| 1039 | +```text | ||||
| 1040 | +Phase: | ||||
| 1041 | +Start/finish timestamp: | ||||
| 1042 | +What was actually done: | ||||
| 1043 | +Artifacts created: | ||||
| 1044 | +Tests passed: | ||||
| 1045 | +Tests failed: | ||||
| 1046 | +Unproved statements or unresolved citations: | ||||
| 1047 | +Decision and justification: | ||||
| 1048 | +Next phase action: | ||||
| 1049 | +``` | ||||
| 1050 | + | ||||
| 1051 | +If the phase is unsuccessful, do not declare victory. Diagnose whether the blocker is (i) mathematical falsehood, (ii) missing assumptions, (iii) missing data/library access, (iv) exhausted compute budget, (v) conflicts in the repository or (vi) publication-priority overlap. Handle the issue using a scientifically defensible fallback, record the limits and continue. Do not allow a failed ambitious theorem to prevent producing the strongest valid WP28 manuscript attainable. | ||||
| 1052 | + | ||||
| 1053 | +### Final instruction to Claude Code | ||||
| 1054 | + | ||||
| 1055 | +**Start immediately.** Inspect the UQO research repository and the supplied PAMLE prior draft, preserve the WP28 identity, reproduce the original math and Monte Carlo, perform a serious priority audit, derive and verify the strongest provable extension, implement fair competing estimators, execute actual experiments, and write a polished English academic paper with full proofs and transparent caveats. Compile and visually validate the final PDF. Keep scientific honesty above ambition, and give Simon-Pierre Boucher the complete, reproducible WP28 package—not a promise, outline, or fictional result. | ||||
added
research/corpus_manifest.csv
+15 −0
@@ -0,0 +1,15 @@ | |||||
| 1 | +wp,url,retrieved_utc,http_status,bytes,sha256,local_file | ||||
| 2 | +WP15,https://git.spboucher.ai/raw/wp15_uqo/main/docs/CLAUDE.md,2026-10-30T03:01:13Z,200,56305,2dd19c59fd320ee5fcdbb25f9ebd41b08b612703573cd8af119858e21a521b77,research/corpus/WP15_CLAUDE.md | ||||
| 3 | +WP15_PROMPT,https://git.spboucher.ai/raw/wp15_uqo/main/docs/PROMPT_INITIAL_CLAUDE.md,2026-10-30T03:01:13Z,200,56305,2dd19c59fd320ee5fcdbb25f9ebd41b08b612703573cd8af119858e21a521b77,research/corpus/WP15_PROMPT_PROMPT_INITIAL_CLAUDE.md | ||||
| 4 | +WP18,https://git.spboucher.ai/raw/wp18_uqo/main/CLAUDE.md,2026-10-30T03:01:13Z,200,12000,f538d6fe2483c975e45a0eed10b12e506ef2d7e20d48b16985c97aad17bc6779,research/corpus/WP18_CLAUDE.md | ||||
| 5 | +WP19,https://git.spboucher.ai/raw/wp19_uqo/main/CLAUDE.md,2026-10-30T03:01:14Z,200,9590,2afdcd653423f83a24bc34cedc69589dc90cd372064134f28fddb6e771404a3b,research/corpus/WP19_CLAUDE.md | ||||
| 6 | +WP20,https://git.spboucher.ai/raw/wp20_uqo/main/CLAUDE.md,2026-10-30T03:01:14Z,200,18756,388ca2431215e4894f6b935a379a6db34a2f1d7d72cd42d188d75ed6c6fefddf,research/corpus/WP20_CLAUDE.md | ||||
| 7 | +WP21,https://git.spboucher.ai/raw/wp21_uqo/main/CLAUDE.md,2026-10-30T03:01:14Z,200,9870,692a6e50b3cf1d026a4bc12201759527ea3336e299bfd4786d3f635fff292b98,research/corpus/WP21_CLAUDE.md | ||||
| 8 | +WP22,https://git.spboucher.ai/raw/wp22_uqo/main/CLAUDE.md,2026-10-30T03:01:14Z,200,16077,b9eb747485cff5a1caa115f0d9138ed925d86915aa77813862b4059bd6d45da5,research/corpus/WP22_CLAUDE.md | ||||
| 9 | +WP23,https://git.spboucher.ai/raw/wp23_uqo/main/CLAUDE.md,2026-10-30T03:01:14Z,200,9474,0f5ebcb5ec63d04392a4872530a43706535f1f8c00e6a3f61bdaaa34d1096cf0,research/corpus/WP23_CLAUDE.md | ||||
| 10 | +WP24,https://git.spboucher.ai/raw/wp24_uqo/main/CLAUDE.md,2026-10-30T03:01:14Z,200,18802,02ae00f871fffd7937e9cd7ec121c53367addd9b5b709915bf6921adfa705347,research/corpus/WP24_CLAUDE.md | ||||
| 11 | +WP25,https://git.spboucher.ai/raw/wp25_uqo/main/CLAUDE.md,2026-10-30T03:01:14Z,200,14054,69f5ee82532d14513986c8f53f1b0981a2f7311dc0fc3b26d844610ccc80bf8b,research/corpus/WP25_CLAUDE.md | ||||
| 12 | +WP26,https://git.spboucher.ai/raw/wp26_uqo/main/CLAUDE.md,2026-10-30T03:01:15Z,200,18482,49afcce91475e5e145b4bd49d29486065c8c613a402b51fdb9baa43c88f4b330,research/corpus/WP26_CLAUDE.md | ||||
| 13 | +WP27_BRIEF,https://git.spboucher.ai/raw/wp27_uqo/main/docs/DESIGN-BRIEF.md,2026-10-30T03:01:15Z,200,5231,72dc7ab846c6d8f8e0cc4101b6bdb600884179e9467c43fddfd3aece395e236e,research/corpus/WP27_BRIEF_DESIGN-BRIEF.md | ||||
| 14 | +WP27,https://git.spboucher.ai/raw/wp27_uqo/main/CLAUDE.md,2026-10-30T03:01:15Z,404,0,, | ||||
| 15 | +WP28,https://git.spboucher.ai/raw/wp28_uqo/main/CLAUDE.md,2026-10-30T03:01:15Z,200,67200,c6c50e319f971b01fa0662840feef177d7bc896526956b0b7a3cf7a83f36246d,research/corpus/WP28_CLAUDE.md | ||||
added
research/verify_cache/https_api_crossref_org_works_10_1002_2Fadma_202413523
+1 −0
@@ -0,0 +1 @@ | |||||
| 1 | +{"status":"ok","message-type":"work","message-version":"1.0.0","message":{"indexed":{"date-parts":[[2026,10,28]],"date-time":"2026-10-28T04:16:51Z","timestamp":1793161011329,"version":"4.5.0"},"reference-count":47,"publisher":"Wiley","issue":"22","license":[{"start":{"date-parts":[[2024,12,18]],"date-time":"2024-12-18T00:00:00Z","timestamp":1734480000000},"content-version":"am","delay-in-days":0,"URL":"http:\/\/creativecommons.org\/licenses\/by-nc\/4.0\/"},{"start":{"date-parts":[[2024,12,18]],"date-time":"2024-12-18T00:00:00Z","timestamp":1734480000000},"content-version":"vor","delay-in-days":0,"URL":"http:\/\/creativecommons.org\/licenses\/by-nc\/4.0\/"},{"start":{"date-parts":[[2024,12,18]],"date-time":"2024-12-18T00:00:00Z","timestamp":1734480000000},"content-version":"tdm","delay-in-days":0,"URL":"http:\/\/doi.wiley.com\/10.1002\/tdm_license_1.1"}],"funder":[{"DOI":"10.13039\/100000199","name":"U.S. Department of Agriculture","doi-asserted-by":"publisher","award":["2021\u201069012\u201035978"],"award-info":[{"award-number":["2021\u201069012\u201035978"]}],"id":[{"id":"10.13039\/100000199","id-type":"DOI","asserted-by":"publisher"}]},{"DOI":"10.13039\/100000183","name":"Army Research Office","doi-asserted-by":"publisher","award":["79058LSCSB"],"award-info":[{"award-number":["79058LSCSB"]}],"id":[{"id":"10.13039\/100000183","id-type":"DOI","asserted-by":"publisher"}]},{"DOI":"10.13039\/100000183","name":"Army Research Office","doi-asserted-by":"publisher","award":["W911NF\u201022\u20102\u20100213"],"award-info":[{"award-number":["W911NF\u201022\u20102\u20100213"]}],"id":[{"id":"10.13039\/100000183","id-type":"DOI","asserted-by":"publisher"}]},{"DOI":"10.13039\/100000183","name":"Army Research Office","doi-asserted-by":"publisher","award":["W911NF2120130"],"award-info":[{"award-number":["W911NF2120130"]}],"id":[{"id":"10.13039\/100000183","id-type":"DOI","asserted-by":"publisher"}]},{"DOI":"10.13039\/100000002","name":"National Institutes of Health","doi-asserted-by":"publisher","award":["U01EB014976"],"award-info":[{"award-number":["U01EB014976"]}],"id":[{"id":"10.13039\/100000002","id-type":"DOI","asserted-by":"publisher"}]},{"DOI":"10.13039\/100000002","name":"National Institutes of Health","doi-asserted-by":"publisher","award":["R01AR077793"],"award-info":[{"award-number":["R01AR077793"]}],"id":[{"id":"10.13039\/100000002","id-type":"DOI","asserted-by":"publisher"}]},{"DOI":"10.13039\/501100001711","name":"Schweizerischer Nationalfonds zur F\u00f6rderung der Wissenschaftlichen Forschung","doi-asserted-by":"publisher","award":["#P500PT_214448"],"award-info":[{"award-number":["#P500PT_214448"]}],"id":[{"id":"10.13039\/501100001711","id-type":"DOI","asserted-by":"publisher"}]}],"content-domain":{"domain":["advanced.onlinelibrary.wiley.com"],"crossmark-restriction":true},"short-container-title":["Advanced Materials"],"published-print":{"date-parts":[[2025,6]]},"abstract":"<jats:title>Abstract<\/jats:title>\n <jats:p>A key challenge in artificial intelligence (AI) is the creation of systems capable of autonomously advancing scientific understanding by exploring novel domains, identifying complex patterns, and uncovering previously unseen connections in vast scientific data. In this work, SciAgents, an approach that leverages three core concepts is presented: (1) large\u2010scale ontological knowledge graphs to organize and interconnect diverse scientific concepts, (2) a suite of large language models (LLMs) and data retrieval tools, and (3) multi\u2010agent systems with in\u2010situ learning capabilities. Applied to biologically inspired materials, SciAgents reveals hidden interdisciplinary relationships that were\u00a0previously considered unrelated, achieving a scale, precision, and exploratory power that surpasses human research methods. The framework autonomously generates and refines research hypotheses, elucidating underlying mechanisms, design principles, and unexpected material properties. By integrating these capabilities in a modular fashion, the system yields material discoveries, critiques and improves existing hypotheses, retrieves up\u2010to\u2010date data about existing research, and highlights strengths and limitations. This is achieved by harnessing a \u201cswarm of intelligence\u201d similar to biological systems, providing new avenues for discovery. How this model accelerates the development of advanced materials by unlocking Nature's design principles, resulting in a new biocomposite with enhanced mechanical properties and improved sustainability through energy\u2010efficient production is shown.<\/jats:p>","DOI":"10.1002\/adma.202413523","type":"journal-article","created":{"date-parts":[[2024,12,19]],"date-time":"2024-12-19T02:22:19Z","timestamp":1734574939000},"update-policy":"https:\/\/doi.org\/10.1002\/crossmark_policy","source":"Crossref","is-referenced-by-count":177,"title":["SciAgents: Automating Scientific Discovery Through Bioinspired Multi\u2010Agent Intelligent Graph Reasoning"],"prefix":"10.1002","volume":"37","author":[{"given":"Alireza","family":"Ghafarollahi","sequence":"first","affiliation":[{"name":"Laboratory for Atomistic and Molecular Mechanics (LAMM) Massachusetts Institute of Technology 77 Massachusetts Ave. Cambridge MA 02139 USA"}],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-4173-9659","authenticated-orcid":false,"given":"Markus J.","family":"Buehler","sequence":"additional","affiliation":[{"name":"Laboratory for Atomistic and Molecular Mechanics (LAMM) Center for Computational Science and Engineering Schwarzman College of Computing Massachusetts Institute of Technology 77 Massachusetts Ave. Cambridge MA 02139 USA"}],"role":[{"vocabulary":"crossref","role":"author"}]}],"member":"311","published-online":{"date-parts":[[2024,12,18]]},"reference":[{"key":"e_1_2_8_1_1","doi-asserted-by":"publisher","DOI":"10.1007\/978-3-642-31674-6_8"},{"key":"e_1_2_8_2_1","doi-asserted-by":"publisher","DOI":"10.1039\/D0MH01451F"},{"key":"e_1_2_8_3_1","doi-asserted-by":"publisher","DOI":"10.1016\/j.jmat.2017.08.002"},{"key":"e_1_2_8_4_1","doi-asserted-by":"publisher","DOI":"10.1063\/5.0134317"},{"key":"e_1_2_8_5_1","first-page":"1","author":"Matsumoto M.","year":"2022","journal-title":"MRS Bull."},{"key":"e_1_2_8_6_1","author":"Buehler M. J.","year":"2024","journal-title":"Mach. Learn.: Sci. Technol."},{"key":"e_1_2_8_7_1","doi-asserted-by":"publisher","DOI":"10.1002\/adma.202405163"},{"key":"e_1_2_8_8_1","unstructured":"C.Lu C.Lu R. T.Lange J.Foerster J.Clune D.Ha arXiv preprint arXiv:2408.062922024."},{"key":"e_1_2_8_9_1","doi-asserted-by":"publisher","DOI":"10.1002\/adma.202310006"},{"key":"e_1_2_8_10_1","author":"Lei G.","year":"2024","journal-title":"Digital Discovery"},{"key":"e_1_2_8_11_1","unstructured":"OpenAI arXiv:2303.087742024."},{"key":"e_1_2_8_12_1","volume":"30","author":"Vaswani A.","year":"2017","journal-title":"Adv. Neural Inform. Process. Syst."},{"key":"e_1_2_8_13_1","unstructured":"J.Wei Y.Tay R.Bommasani C.Raffel B.Zoph S.Borgeaud D.Yogatama M.Bosma D.Zhou D.Metzler E. H.Chi T.Hashimoto O.Vinyals P.Liang J.Dean Q.Fedus arXiv preprint arXiv:2206.076822022."},{"key":"e_1_2_8_14_1","unstructured":"H.Touvron L.Martin K.Stone P.Albert A.Almahairi Y.Babaei N.Bashlykov S.Batra P.Bhargava S.Bhosale et\u00a0al. arXiv preprint arXiv:2307.092882023."},{"key":"e_1_2_8_15_1","doi-asserted-by":"publisher","DOI":"10.1007\/s12599-023-00795-x"},{"key":"e_1_2_8_16_1","unstructured":"W. X.Zhao K.Zhou J.Li T.Tang X.Wang Y.Hou Y.Min B.Zhang J.Zhang Z.Dong Y.Du C.Yang Y.Chen Z.Chen J.Jiang R.Ren Y.Li X.Tang Z.Liu P.Liu J.Nie J.Wen arXiv preprint arXiv:2303.182232023."},{"key":"e_1_2_8_17_1","first-page":"1","volume":"24","author":"Chowdhery A.","year":"2023","journal-title":"J. Mach. Learn. Res."},{"key":"e_1_2_8_18_1","unstructured":"S.Gunasekar Y.Zhang J.Aneja C. C. T.Mendes A.Del Giorno S.Gopi M.Javaheripi P.Kauffmann G.deRosa O.Saarikivi A.Salim S.Shah H. S.Behl X.Wang S.Bubeck R.Eldan A. T.Kalai Y. T.Lee Y.Li arXiv preprint arXiv:2306.116442023."},{"key":"e_1_2_8_19_1","unstructured":"A. Q.Jiang A.Sablayrolles A.Mensch C.Bamford D. S.Chaplot D. d. l.Casas F.Bressand G.Lengyel G.Lample L.Saulnier L. R.Lavaud M.Lachaux P.Stock T.Le Scao T.Lavril T.Wang T.Lacroix W.El Sayed arXiv preprint arXiv:2310.068252023."},{"key":"e_1_2_8_20_1","unstructured":"K.Girotra L.Meincke C.Terwiesch K. T.Ulrich Available at SSRN 45260712023."},{"key":"e_1_2_8_21_1","unstructured":"M. J.Buehler ACS Engineering AU2023."},{"key":"e_1_2_8_22_1","doi-asserted-by":"publisher","DOI":"10.1039\/D3DD00113J"},{"key":"e_1_2_8_23_1","first-page":"1","author":"Bran A. M.","year":"2024","journal-title":"Nat. Mach. Intell."},{"key":"e_1_2_8_24_1","doi-asserted-by":"publisher","DOI":"10.1002\/advs.202306724"},{"key":"e_1_2_8_25_1","unstructured":"W.Lu R. K.Luu M. J.Buehler arXiv:2409.034442024."},{"key":"e_1_2_8_26_1","author":"Buehler M. J.","journal-title":"Adv. Funct. Mater."},{"key":"e_1_2_8_27_1","unstructured":"C.Si D.Yang T.Hashimoto arXiv preprint arXiv:2409.041092024."},{"key":"e_1_2_8_28_1","volume":"35","author":"Wei J.","year":"2022","journal-title":"Adv Neural Inf Process Syst"},{"key":"e_1_2_8_29_1","unstructured":"J.White Q.Fu S.Hays M.Sandborn C.Olea H.Gilbert A.Elnashar J.Spencer\u2010Smith D. C.Schmidt arXiv preprint arXiv:2302.113822023."},{"key":"e_1_2_8_30_1","unstructured":"Y.Zhou A. I.Muresanu Z.Han K.Paster S.Pitis H.Chan J.Ba arXiv preprint arXiv:2211.019102022."},{"key":"e_1_2_8_31_1","unstructured":"J.Sun C.Xu L.Tang S.Wang C.Lin Y.Gong H.\u2010Y.Shum J.Guo arXiv preprint arXiv:2307.076972023."},{"key":"e_1_2_8_32_1","doi-asserted-by":"publisher","DOI":"10.1038\/s41524-023-01003-w"},{"key":"e_1_2_8_33_1","unstructured":"S.Pan L.Luo Y.Wang C.Chen J.Wang X.Wu IEEE Transactions on Knowledge and Data Engineering2024."},{"key":"e_1_2_8_34_1","doi-asserted-by":"publisher","DOI":"10.1038\/s41467-024-45563-x"},{"key":"e_1_2_8_35_1","unstructured":"M.Schilling\u2010Wilhelmi M.R\u00edos\u2010Garc\u00eda S.Shabih M. V.Gil S.Miret C. T.Koch J. A.M\u00e1rquez K. M.Jablonka arXiv preprint arXiv:2407.168672024."},{"key":"e_1_2_8_36_1","doi-asserted-by":"publisher","DOI":"10.1016\/j.eml.2024.102131"},{"key":"e_1_2_8_37_1","unstructured":"I.Stewart M.Buehler ChemRxiv2024."},{"key":"e_1_2_8_38_1","doi-asserted-by":"publisher","DOI":"10.1039\/D4DD00013G"},{"key":"e_1_2_8_39_1","unstructured":"A.Ghafarollahi M. J.Buehler arXiv preprint arXiv:2407.100222024."},{"key":"e_1_2_8_40_1","doi-asserted-by":"publisher","DOI":"10.1002\/adem.201200109"},{"key":"e_1_2_8_41_1","doi-asserted-by":"publisher","DOI":"10.1371\/journal.pone.0023911"},{"key":"e_1_2_8_42_1","unstructured":"Q.Wu G.Bansal J.Zhang Y.Wu S.Zhang E.Zhu B.Li L.Jiang X.Zhang C.Wang arXiv preprint arXiv:2308.081552023."},{"key":"e_1_2_8_43_1","unstructured":"Y.Wu T.Yue S.Zhang C.Wang Q.Wu arXiv:2403.11322 2024."},{"key":"e_1_2_8_44_1","unstructured":"Y.Wu F.Jia S.Zhang H.Li E.Zhu Y.Wang Y. T.Lee R.Peng Q.Wu C.Wang inArXiv preprint arXiv:2306.01337 2023."},{"key":"e_1_2_8_45_1","unstructured":"OpenAI API https:\/\/openai.com\/blog\/openai\u2010api."},{"key":"e_1_2_8_46_1","doi-asserted-by":"publisher","DOI":"10.1007\/BF01386390"},{"key":"e_1_2_8_47_1","unstructured":"Q.Wu G.Bansal J.Zhang Y.Wu B.Li E.Zhu L.Jiang X.Zhang S.Zhang J.Liu A.Awadallah R. W.White D.Burger C.Wang arXiv:2308.081552023."}],"container-title":["Advanced Materials"],"original-title":[],"language":"en","link":[{"URL":"https:\/\/advanced.onlinelibrary.wiley.com\/doi\/pdf\/10.1002\/adma.202413523","content-type":"application\/pdf","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/advanced.onlinelibrary.wiley.com\/doi\/full-xml\/10.1002\/adma.202413523","content-type":"application\/xml","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/advanced.onlinelibrary.wiley.com\/doi\/pdf\/10.1002\/adma.202413523","content-type":"application\/pdf","content-version":"vor","intended-application":"syndication"},{"URL":"https:\/\/advanced.onlinelibrary.wiley.com\/doi\/pdf\/10.1002\/adma.202413523","content-type":"unspecified","content-version":"vor","intended-application":"similarity-checking"}],"deposited":{"date-parts":[[2026,2,18]],"date-time":"2026-02-18T05:02:57Z","timestamp":1771390977000},"score":1,"resource":{"primary":{"URL":"https:\/\/advanced.onlinelibrary.wiley.com\/doi\/10.1002\/adma.202413523"}},"subtitle":[],"short-title":[],"issued":{"date-parts":[[2024,12,18]]},"references-count":47,"journal-issue":{"issue":"22","published-print":{"date-parts":[[2025,6]]}},"alternative-id":["10.1002\/adma.202413523"],"URL":"https:\/\/doi.org\/10.1002\/adma.202413523","archive":["Portico"],"relation":{},"ISSN":["0935-9648","1521-4095"],"issn-type":[{"value":"0935-9648","type":"print"},{"value":"1521-4095","type":"electronic"}],"subject":[],"published":{"date-parts":[[2024,12,18]]},"assertion":[{"value":"2024-09-09","order":0,"name":"received","label":"Received","group":{"name":"publication_history","label":"Publication History"}},{"value":"2024-12-18","order":3,"name":"published","label":"Published","group":{"name":"publication_history","label":"Publication History"}}],"article-number":"2413523"}} | ||||
| \ No newline at end of file | |||||
added
research/verify_cache/https_api_crossref_org_works_10_1038_2Fs41586_023_06221_2
+1 −0
@@ -0,0 +1 @@ | |||||
| 1 | +{"status":"ok","message-type":"work","message-version":"1.0.0","message":{"indexed":{"date-parts":[[2026,10,30]],"date-time":"2026-10-30T02:42:35Z","timestamp":1793328155098,"version":"4.5.0"},"reference-count":238,"publisher":"Springer Science and Business Media LLC","issue":"7972","license":[{"start":{"date-parts":[[2023,8,2]],"date-time":"2023-08-02T00:00:00Z","timestamp":1690934400000},"content-version":"tdm","delay-in-days":0,"URL":"https:\/\/www.springernature.com\/gp\/researchers\/text-and-data-mining"},{"start":{"date-parts":[[2023,8,2]],"date-time":"2023-08-02T00:00:00Z","timestamp":1690934400000},"content-version":"vor","delay-in-days":0,"URL":"https:\/\/www.springernature.com\/gp\/researchers\/text-and-data-mining"}],"content-domain":{"domain":["link.springer.com"],"crossmark-restriction":false},"short-container-title":["Nature"],"published-print":{"date-parts":[[2023,8,3]]},"DOI":"10.1038\/s41586-023-06221-2","type":"journal-article","created":{"date-parts":[[2023,8,2]],"date-time":"2023-08-02T12:02:13Z","timestamp":1690977733000},"page":"47-60","update-policy":"https:\/\/doi.org\/10.1007\/springer_crossmark_policy","source":"Crossref","is-referenced-by-count":1840,"title":["Scientific discovery in the age of artificial intelligence"],"prefix":"10.1038","volume":"620","author":[{"ORCID":"https:\/\/orcid.org\/0000-0002-1691-024X","authenticated-orcid":false,"given":"Hanchen","family":"Wang","sequence":"first","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Tianfan","family":"Fu","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Yuanqi","family":"Du","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Wenhao","family":"Gao","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Kexin","family":"Huang","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Ziming","family":"Liu","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0003-1097-803X","authenticated-orcid":false,"given":"Payal","family":"Chandak","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0003-2030-2367","authenticated-orcid":false,"given":"Shengchao","family":"Liu","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-3512-0665","authenticated-orcid":false,"given":"Peter","family":"Van Katwyk","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Andreea","family":"Deac","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Anima","family":"Anandkumar","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Karianne","family":"Bergen","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-4441-7225","authenticated-orcid":false,"given":"Carla P.","family":"Gomes","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Shirley","family":"Ho","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-7466-7997","authenticated-orcid":false,"given":"Pushmeet","family":"Kohli","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Joan","family":"Lasenby","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-5411-923X","authenticated-orcid":false,"given":"Jure","family":"Leskovec","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Tie-Yan","family":"Liu","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Arjun","family":"Manrai","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0001-9388-2281","authenticated-orcid":false,"given":"Debora","family":"Marks","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Bharath","family":"Ramsundar","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Le","family":"Song","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Jimeng","family":"Sun","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Jian","family":"Tang","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Petar","family":"Veli\u010dkovi\u0107","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Max","family":"Welling","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Linfeng","family":"Zhang","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-8271-8723","authenticated-orcid":false,"given":"Connor W.","family":"Coley","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-9322-3515","authenticated-orcid":false,"given":"Yoshua","family":"Bengio","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0001-8530-7228","authenticated-orcid":false,"given":"Marinka","family":"Zitnik","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]}],"member":"297","published-online":{"date-parts":[[2023,8,2]]},"reference":[{"key":"6221_CR1","doi-asserted-by":"publisher","first-page":"436","DOI":"10.1038\/nature14539","volume":"521","author":"Y LeCun","year":"2015","unstructured":"LeCun, Y., Bengio, Y. & Hinton, G. Deep learning. Nature 521, 436\u2013444 (2015). This survey summarizes key elements of deep learning and its development in speech recognition, computer vision and and natural language processing.","journal-title":"Nature"},{"key":"6221_CR2","doi-asserted-by":"publisher","first-page":"921","DOI":"10.1086\/710520","volume":"87","author":"HW de Regt","year":"2020","unstructured":"de Regt, H. W. Understanding, values, and the aims of science. Phil. Sci. 87, 921\u2013932 (2020).","journal-title":"Phil. Sci."},{"key":"6221_CR3","unstructured":"Pickstone, J. V. Ways of Knowing: A New History of Science, Technology, and Medicine (Univ. Chicago Press, 2001)."},{"key":"6221_CR4","doi-asserted-by":"crossref","unstructured":"Han, J. et al. Deep potential: a general representation of a many-body potential energy surface. Commun. Comput. Phys. 23, 629\u2013639 (2018). This paper introduced a deep neural network architecture that learns the potential energy surface of many-body systems while respecting the underlying symmetries of the system by incorporating group theory.","DOI":"10.4208\/cicp.OA-2017-0213"},{"key":"6221_CR5","doi-asserted-by":"publisher","first-page":"L4","DOI":"10.3847\/2041-8213\/ab0e85","volume":"875","author":"K Akiyama","year":"2019","unstructured":"Akiyama, K. et al. First M87 Event Horizon Telescope results. IV. Imaging the central supermassive black hole. Astrophys. J. Lett. 875, L4 (2019).","journal-title":"Astrophys. J. Lett."},{"key":"6221_CR6","unstructured":"Wagner, A. Z. Constructions in combinatorics via neural networks. Preprint at https:\/\/arxiv.org\/abs\/2104.14516 (2021)."},{"key":"6221_CR7","doi-asserted-by":"publisher","first-page":"eaax1566","DOI":"10.1126\/science.aax1566","volume":"365","author":"CW Coley","year":"2019","unstructured":"Coley, C. W. et al. A robotic platform for flow synthesis of organic compounds informed by AI planning. Science 365, eaax1566 (2019).","journal-title":"Science"},{"key":"6221_CR8","unstructured":"Bommasani, R. et al. On the opportunities and risks of foundation models. Preprint at https:\/\/arxiv.org\/abs\/2108.07258 (2021)."},{"key":"6221_CR9","doi-asserted-by":"publisher","first-page":"70","DOI":"10.1038\/s41586-021-04086-x","volume":"600","author":"A Davies","year":"2021","unstructured":"Davies, A. et al. Advancing mathematics by guiding human intuition with AI. Nature 600, 70\u201374 (2021). This paper explores how AI can aid the development of pure mathematics by guiding mathematical intuition.","journal-title":"Nature"},{"key":"6221_CR10","doi-asserted-by":"publisher","first-page":"583","DOI":"10.1038\/s41586-021-03819-2","volume":"596","author":"J Jumper","year":"2021","unstructured":"Jumper, J. et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583\u2013589 (2021).This study was the first to demonstrate the ability to predict protein folding structures using AI methods with a high degree of accuracy, achieving results that are at or near the experimental resolution. This accomplishment is particularly noteworthy, as predicting protein folding has been a grand challenge in the field of molecular biology for over 50 years.","journal-title":"Nature"},{"key":"6221_CR11","doi-asserted-by":"publisher","first-page":"688","DOI":"10.1016\/j.cell.2020.01.021","volume":"180","author":"JM Stokes","year":"2020","unstructured":"Stokes, J. M. et al. A deep learning approach to antibiotic discovery. Cell 180, 688\u2013702 (2020).","journal-title":"Cell"},{"key":"6221_CR12","doi-asserted-by":"publisher","first-page":"3","DOI":"10.1002\/(SICI)1098-1128(199601)16:1<3::AID-MED1>3.0.CO;2-6","volume":"16","author":"RS Bohacek","year":"1996","unstructured":"Bohacek, R. S., McMartin, C. & Guida, W. C. The art and practice of structure-based drug design: a molecular modeling perspective. Med. Res. Rev. 16, 3\u201350 (1996).","journal-title":"Med. Res. Rev."},{"key":"6221_CR13","doi-asserted-by":"crossref","unstructured":"Bileschi, M. L. et al. Using deep learning to annotate the protein universe. Nat. Biotechnol. 40, 932\u2013937 (2022).","DOI":"10.1038\/s41587-021-01179-w"},{"key":"6221_CR14","doi-asserted-by":"publisher","first-page":"77","DOI":"10.1038\/s41586-020-2939-8","volume":"588","author":"MG Bellemare","year":"2020","unstructured":"Bellemare, M. G. et al. Autonomous navigation of stratospheric balloons using reinforcement learning. Nature 588, 77\u201382 (2020). This paper describes a reinforcement-learning algorithm for navigating a super-pressure balloon in the stratosphere, making real-time decisions in the changing environment.","journal-title":"Nature"},{"key":"6221_CR15","doi-asserted-by":"publisher","first-page":"95","DOI":"10.1038\/s41586-019-1335-8","volume":"571","author":"V Tshitoyan","year":"2019","unstructured":"Tshitoyan, V. et al. Unsupervised word embeddings capture latent knowledge from materials science literature. Nature 571, 95\u201398 (2019).","journal-title":"Nature"},{"key":"6221_CR16","doi-asserted-by":"publisher","first-page":"143001","DOI":"10.1103\/PhysRevLett.120.143001","volume":"120","author":"L Zhang","year":"2018","unstructured":"Zhang, L. et al. Deep potential molecular dynamics: a scalable model with the accuracy of quantum mechanics. Phys. Rev. Lett. 120, 143001 (2018).","journal-title":"Phys. Rev. Lett."},{"key":"6221_CR17","unstructured":"Deiana, A. M. et al. Applications and techniques for fast machine learning in science. Front. Big Data 5, 787421 (2022)."},{"key":"6221_CR18","doi-asserted-by":"crossref","unstructured":"Karagiorgi, G. et al. Machine learning in the search for new fundamental physics. Nat. Rev. Phys. 4, 399\u2013412 (2022).","DOI":"10.1038\/s42254-022-00455-1"},{"key":"6221_CR19","doi-asserted-by":"crossref","unstructured":"Zhou, C. & Paffenroth, R. C. Anomaly detection with robust deep autoencoders. In ACM SIGKDD International Conference on Knowledge Discovery and Data Mining 665\u2013674 (2017).","DOI":"10.1145\/3097983.3098052"},{"key":"6221_CR20","doi-asserted-by":"publisher","first-page":"504","DOI":"10.1126\/science.1127647","volume":"313","author":"GE Hinton","year":"2006","unstructured":"Hinton, G. E. & Salakhutdinov, R. R. Reducing the dimensionality of data with neural networks. Science 313, 504\u2013507 (2006).","journal-title":"Science"},{"key":"6221_CR21","doi-asserted-by":"publisher","first-page":"124201","DOI":"10.1088\/1361-6633\/ac36b9","volume":"84","author":"G Kasieczka","year":"2021","unstructured":"Kasieczka, G. et al. The LHC Olympics 2020 a community challenge for anomaly detection in high energy physics. Rep. Prog. Phys. 84, 124201 (2021).","journal-title":"Rep. Prog. Phys."},{"key":"6221_CR22","doi-asserted-by":"publisher","first-page":"154","DOI":"10.1038\/s42256-022-00441-3","volume":"4","author":"E Govorkova","year":"2022","unstructured":"Govorkova, E. et al. Autoencoders on field-programmable gate arrays for real-time, unsupervised new physics detection at 40 MHz at the Large Hadron Collider. Nat. Mach. Intell. 4, 154\u2013161 (2022).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR23","doi-asserted-by":"publisher","first-page":"598","DOI":"10.1038\/s43588-021-00126-8","volume":"1","author":"M Chamberland","year":"2021","unstructured":"Chamberland, M. et al. Detecting microstructural deviations in individuals with deep diffusion MRI tractometry. Nat. Comput. Sci. 1, 598\u2013606 (2021).","journal-title":"Nat. Comput. Sci."},{"key":"6221_CR24","doi-asserted-by":"publisher","first-page":"3004","DOI":"10.1038\/s41598-020-59881-9","volume":"10","author":"M Rafique","year":"2020","unstructured":"Rafique, M. et al. Delegated regressor, a robust approach for automated anomaly detection in the soil radon time series data. Sci. Rep. 10, 3004 (2020).","journal-title":"Sci. Rep."},{"key":"6221_CR25","doi-asserted-by":"publisher","first-page":"12142","DOI":"10.1038\/s41598-020-68662-3","volume":"10","author":"VP Pastore","year":"2020","unstructured":"Pastore, V. P. et al. Annotation-free learning of plankton for classification and anomaly detection. Sci. Rep. 10, 12142 (2020).","journal-title":"Sci. Rep."},{"key":"6221_CR26","doi-asserted-by":"publisher","first-page":"151","DOI":"10.1038\/s41550-017-0321-z","volume":"2","author":"B Naul","year":"2018","unstructured":"Naul, B. et al. A recurrent neural network for classification of unevenly sampled variable stars. Nat. Astron. 2, 151\u2013155 (2018).","journal-title":"Nat. Astron."},{"key":"6221_CR27","unstructured":"Lee, D.-H. et al. Pseudo-label: the simple and efficient semi-supervised learning method for deep neural networks. In ICML Workshop on Challenges in Representation Learning (2013)."},{"key":"6221_CR28","unstructured":"Zhou, D. et al. Learning with local and global consistency. In Advances in Neural Information Processing Systems 16, 321\u2013328 (2003)."},{"key":"6221_CR29","doi-asserted-by":"publisher","first-page":"221","DOI":"10.1038\/nmeth.2340","volume":"10","author":"P Radivojac","year":"2013","unstructured":"Radivojac, P. et al. A large-scale evaluation of computational protein function prediction. Nat. Methods 10, 221\u2013227 (2013).","journal-title":"Nat. Methods"},{"key":"6221_CR30","doi-asserted-by":"publisher","first-page":"695","DOI":"10.1038\/s41592-019-0466-z","volume":"16","author":"N Barkas","year":"2019","unstructured":"Barkas, N. et al. Joint analysis of heterogeneous single-cell RNA-seq dataset collections. Nat. Methods 16, 695\u2013698 (2019).","journal-title":"Nat. Methods"},{"key":"6221_CR31","doi-asserted-by":"publisher","first-page":"696","DOI":"10.1038\/s41929-018-0142-1","volume":"1","author":"K Tran","year":"2018","unstructured":"Tran, K. & Ulissi, Z. W. Active learning across intermetallics to guide discovery of electrocatalysts for CO2 reduction and H2 evolution. Nat. Catal. 1, 696\u2013703 (2018).","journal-title":"Nat. Catal."},{"key":"6221_CR32","doi-asserted-by":"publisher","first-page":"2312","DOI":"10.1038\/s41467-021-22437-0","volume":"12","author":"KM Jablonka","year":"2021","unstructured":"Jablonka, K. M. et al. Bias free multiobjective active learning for materials design and discovery. Nat. Commun. 12, 2312 (2021).","journal-title":"Nat. Commun."},{"key":"6221_CR33","doi-asserted-by":"publisher","first-page":"5612","DOI":"10.1038\/s41467-021-25757-3","volume":"12","author":"R Roussel","year":"2021","unstructured":"Roussel, R. et al. Turn-key constrained parameter space exploration for particle accelerators using Bayesian active learning. Nat. Commun. 12, 5612 (2021).","journal-title":"Nat. Commun."},{"key":"6221_CR34","unstructured":"Ratner, A. J. et al. Data programming: creating large training sets, quickly. In Advances in Neural Information Processing Systems 29, 3567\u20133575 (2016)."},{"key":"6221_CR35","doi-asserted-by":"crossref","unstructured":"Ratner, A. et al. Snorkel: rapid training data creation with weak supervision. In International Conference on Very Large Data Bases 11, 269\u2013282 (2017). This paper presents a weakly-supervised AI system designed to annotate massive amounts of data using labeling functions.","DOI":"10.14778\/3157794.3157797"},{"key":"6221_CR36","doi-asserted-by":"publisher","first-page":"139","DOI":"10.21468\/SciPostPhys.10.6.139","volume":"10","author":"A Butter","year":"2021","unstructured":"Butter, A. et al. GANplifying event samples. SciPost Phys. 10, 139 (2021).","journal-title":"SciPost Phys."},{"key":"6221_CR37","unstructured":"Brown, T. et al. Language models are few-shot learners. In Advances in Neural Information Processing Systems 33, 1877\u20131901 (2020)."},{"key":"6221_CR38","unstructured":"Ramesh, A. et al. Zero-shot text-to-image generation. In International Conference on Machine Learning 139, 8821\u20138831 (2021)."},{"key":"6221_CR39","doi-asserted-by":"publisher","first-page":"445","DOI":"10.1038\/nature14540","volume":"521","author":"ML Littman","year":"2015","unstructured":"Littman, M. L. Reinforcement learning improves behaviour from evaluative feedback. Nature 521, 445\u2013451 (2015).","journal-title":"Nature"},{"key":"6221_CR40","doi-asserted-by":"crossref","unstructured":"Cubuk, E. D. et al. Autoaugment: learning augmentation strategies from data. In IEEE Conference on Computer Vision and Pattern Recognition 113\u2013123 (2019).","DOI":"10.1109\/CVPR.2019.00020"},{"key":"6221_CR41","doi-asserted-by":"crossref","unstructured":"Reed, C. J. et al. Selfaugment: automatic augmentation policies for self-supervised learning. In IEEE Conference on Computer Vision and Pattern Recognition 2674\u20132683 (2021).","DOI":"10.1109\/CVPR46437.2021.00270"},{"key":"6221_CR42","unstructured":"ATLAS Collaboration et al. Deep generative models for fast photon shower simulation in ATLAS. Preprint at https:\/\/arxiv.org\/abs\/2210.06204 (2022)."},{"key":"6221_CR43","doi-asserted-by":"publisher","first-page":"3257","DOI":"10.1109\/TMI.2019.2927182","volume":"39","author":"F Mahmood","year":"2019","unstructured":"Mahmood, F. et al. Deep adversarial training for multi-organ nuclei segmentation in histopathology images. IEEE Trans. Med. Imaging 39, 3257\u20133267 (2019).","journal-title":"IEEE Trans. Med. Imaging"},{"key":"6221_CR44","doi-asserted-by":"crossref","unstructured":"Teixeira, B. et al. Generating synthetic X-ray images of a person from the surface geometry. In IEEE Conference on Computer Vision and Pattern Recognition 9059\u20139067 (2018).","DOI":"10.1109\/CVPR.2018.00944"},{"key":"6221_CR45","doi-asserted-by":"publisher","first-page":"34","DOI":"10.1038\/s42256-019-0137-x","volume":"2","author":"D Lee","year":"2020","unstructured":"Lee, D., Moon, W.-J. & Ye, J. C. Assessing the importance of magnetic resonance contrasts using collaborative generative adversarial networks. Nat. Mach. Intell. 2, 34\u201342 (2020).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR46","doi-asserted-by":"publisher","first-page":"299","DOI":"10.1038\/s42256-021-00322-1","volume":"3","author":"S Kench","year":"2021","unstructured":"Kench, S. & Cooper, S. J. Generating three-dimensional structures from a two-dimensional slice with generative adversarial network-based dimensionality expansion. Nat. Mach. Intell. 3, 299\u2013305 (2021).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR47","doi-asserted-by":"publisher","first-page":"540","DOI":"10.1038\/s42256-020-0222-1","volume":"2","author":"C Wan","year":"2020","unstructured":"Wan, C. & Jones, D. T. Protein function prediction is improved by creating synthetic feature samples with generative adversarial networks. Nat. Mach. Intell. 2, 540\u2013550 (2020).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR48","doi-asserted-by":"publisher","first-page":"324","DOI":"10.1038\/s42256-021-00310-5","volume":"3","author":"D Repecka","year":"2021","unstructured":"Repecka, D. et al. Expanding functional protein sequence spaces using generative adversarial networks. Nat. Mach. Intell. 3, 324\u2013333 (2021).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR49","doi-asserted-by":"publisher","first-page":"166","DOI":"10.1038\/s41467-019-14018-z","volume":"11","author":"M Marouf","year":"2020","unstructured":"Marouf, M. et al. Realistic in silico generation and augmentation of single-cell RNA-seq data using generative adversarial networks. Nat. Commun. 11, 166 (2020).","journal-title":"Nat. Commun."},{"key":"6221_CR50","doi-asserted-by":"publisher","first-page":"452","DOI":"10.1038\/nature14541","volume":"521","author":"Z Ghahramani","year":"2015","unstructured":"Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452\u2013459 (2015).This survey provides an introduction to probabilistic machine learning, which involves the representation and manipulation of uncertainty in models and predictions, playing a central role in scientific data analysis.","journal-title":"Nature"},{"key":"6221_CR51","doi-asserted-by":"publisher","first-page":"118","DOI":"10.1007\/JHEP02(2015)118","volume":"2015","author":"J Cogan","year":"2015","unstructured":"Cogan, J. et al. Jet-images: computer vision inspired techniques for jet tagging. J. High Energy Phys. 2015, 118 (2015).","journal-title":"J. High Energy Phys."},{"key":"6221_CR52","doi-asserted-by":"publisher","first-page":"606","DOI":"10.1038\/s41587-021-01092-2","volume":"40","author":"W Zhao","year":"2022","unstructured":"Zhao, W. et al. Sparse deconvolution improves the resolution of live-cell super-resolution fluorescence microscopy. Nat. Biotechnol. 40, 606\u2013617 (2022).","journal-title":"Nat. Biotechnol."},{"key":"6221_CR53","doi-asserted-by":"publisher","first-page":"1200","DOI":"10.1038\/s41592-020-00979-3","volume":"17","author":"M Brbi\u0107","year":"2020","unstructured":"Brbi\u0107, M. et al. MARS: discovering novel cell types across heterogeneous single-cell experiments. Nat. Methods 17, 1200\u20131206 (2020).","journal-title":"Nat. Methods"},{"key":"6221_CR54","doi-asserted-by":"publisher","first-page":"194","DOI":"10.1038\/s41592-020-01048-5","volume":"18","author":"C Qiao","year":"2021","unstructured":"Qiao, C. et al. Evaluation and development of deep neural networks for image super-resolution in optical microscopy. Nat. Methods 18, 194\u2013202 (2021).","journal-title":"Nat. Methods"},{"key":"6221_CR55","doi-asserted-by":"publisher","first-page":"182001","DOI":"10.1103\/PhysRevLett.124.182001","volume":"124","author":"A Andreassen","year":"2020","unstructured":"Andreassen, A. et al. OmniFold: a method to simultaneously unfold all observables. Phys. Rev. Lett. 124, 182001 (2020).","journal-title":"Phys. Rev. Lett."},{"key":"6221_CR56","doi-asserted-by":"crossref","unstructured":"Bergenstr\u00e5hle, L. et al. Super-resolved spatial transcriptomics by deep data fusion. Nat. Biotechnol. 40, 476\u2013479 (2021).","DOI":"10.1038\/s41587-021-01075-3"},{"key":"6221_CR57","doi-asserted-by":"crossref","unstructured":"Vincent, P. et al. Extracting and composing robust features with denoising autoencoders. In International Conference on Machine Learning 1096\u20131103 (2008).","DOI":"10.1145\/1390156.1390294"},{"key":"6221_CR58","unstructured":"Kingma, D. P. & Welling, M. Auto-encoding variational Bayes. In International Conference on Learning Representations (2014)."},{"key":"6221_CR59","doi-asserted-by":"publisher","first-page":"390","DOI":"10.1038\/s41467-018-07931-2","volume":"10","author":"G Eraslan","year":"2019","unstructured":"Eraslan, G. et al. Single-cell RNA-seq denoising using a deep count autoencoder. Nat. Commun. 10, 390 (2019).","journal-title":"Nat. Commun."},{"key":"6221_CR60","unstructured":"Goodfellow, I., Bengio, Y. & Courville, A. Deep Learning (MIT Press, 2016)."},{"key":"6221_CR61","doi-asserted-by":"publisher","first-page":"607","DOI":"10.1038\/381607a0","volume":"381","author":"BA Olshausen","year":"1996","unstructured":"Olshausen, B. A. & Field, D. J. Emergence of simple-cell receptive field properties by learning a sparse code for natural images. Nature 381, 607\u2013609 (1996).","journal-title":"Nature"},{"key":"6221_CR62","unstructured":"Bengio, Y. Deep learning of representations for unsupervised and transfer learning. In ICML Workshop on Unsupervised and Transfer Learning (2012)."},{"key":"6221_CR63","doi-asserted-by":"publisher","first-page":"1914","DOI":"10.1038\/s41467-022-29443-w","volume":"13","author":"NS Detlefsen","year":"2022","unstructured":"Detlefsen, N. S., Hauberg, S. & Boomsma, W. Learning meaningful representations of protein sequences. Nat. Commun. 13, 1914 (2022).","journal-title":"Nat. Commun."},{"key":"6221_CR64","doi-asserted-by":"publisher","first-page":"38","DOI":"10.1038\/nbt.4314","volume":"37","author":"E Becht","year":"2019","unstructured":"Becht, E. et al. Dimensionality reduction for visualizing single-cell data using UMAP. Nat. Biotechnol. 37, 38\u201344 (2019).","journal-title":"Nat. Biotechnol."},{"key":"6221_CR65","doi-asserted-by":"publisher","first-page":"18","DOI":"10.1109\/MSP.2017.2693418","volume":"34","author":"MM Bronstein","year":"2017","unstructured":"Bronstein, M. M. et al. Geometric deep learning: going beyond euclidean data. IEEE Signal Process Mag. 34, 18\u201342 (2017).","journal-title":"IEEE Signal Process Mag."},{"key":"6221_CR66","doi-asserted-by":"publisher","first-page":"393","DOI":"10.1126\/science.177.4047.393","volume":"177","author":"PW Anderson","year":"1972","unstructured":"Anderson, P. W. More is different: broken symmetry and the nature of the hierarchical structure of science. Science 177, 393\u2013396 (1972).","journal-title":"Science"},{"key":"6221_CR67","doi-asserted-by":"crossref","unstructured":"Qiao, Z. et al. Informing geometric deep learning with electronic interactions to accelerate quantum chemistry. Proc. Natl Acad. Sci. USA 119, e2205221119 (2022).","DOI":"10.1073\/pnas.2205221119"},{"key":"6221_CR68","unstructured":"Bogatskiy, A. et al. Symmetry group equivariant architectures for physics. Preprint at https:\/\/arxiv.org\/abs\/2203.06153 (2022)."},{"key":"6221_CR69","unstructured":"Bronstein, M. M. et al. Geometric deep learning: grids, groups, graphs, geodesics, and gauges. Preprint at https:\/\/arxiv.org\/abs\/2104.13478 (2021)."},{"key":"6221_CR70","doi-asserted-by":"publisher","first-page":"1047","DOI":"10.1126\/science.abe5650","volume":"373","author":"RJL Townshend","year":"2021","unstructured":"Townshend, R. J. L. et al. Geometric deep learning of RNA structure. Science 373, 1047\u20131051 (2021).","journal-title":"Science"},{"key":"6221_CR71","doi-asserted-by":"crossref","unstructured":"Wicky, B. I. M. et al. Hallucinating symmetric protein assemblies. Science 378, 56\u201361 (2022).","DOI":"10.1126\/science.add1964"},{"key":"6221_CR72","unstructured":"Kipf, T. N. & Welling, M. Semi-supervised classification with graph convolutional networks. In International Conference on Learning Representations (2017)."},{"key":"6221_CR73","unstructured":"Veli\u010dkovi\u0107, P. et al. Graph attention networks. In International Conference on Learning Representations (2018)."},{"key":"6221_CR74","unstructured":"Hamilton, W. L., Ying, Z. & Leskovec, J. Inductive representation learning on large graphs. In Advances in Neural Information Processing Systems 30, 1024\u20131034 (2017)."},{"key":"6221_CR75","unstructured":"Gilmer, J. et al. Neural message passing for quantum chemistry. In International Conference on Machine Learning 1263\u20131272 (2017)."},{"key":"6221_CR76","doi-asserted-by":"crossref","unstructured":"Li, M. M., Huang, K. & Zitnik, M. Graph representation learning in biomedicine and healthcare. Nat. Biomed. Eng. 6, 1353\u20131369 (2022).","DOI":"10.1038\/s41551-022-00942-x"},{"key":"6221_CR77","unstructured":"Satorras, V. G., Hoogeboom, E. & Welling, M. E(n) equivariant graph neural networks. In International Conference on Machine Learning 9323\u20139332 (2021). This study incorporates principles of physics into the design of neural models, advancing the field of equivariant machine learning."},{"key":"6221_CR78","unstructured":"Thomas, N. et al. Tensor field networks: rotation-and translation-equivariant neural networks for 3D point clouds. Preprint at https:\/\/arxiv.org\/abs\/1802.08219 (2018)."},{"key":"6221_CR79","unstructured":"Finzi, M. et al. Generalizing convolutional neural networks for equivariance to lie groups on arbitrary continuous data. In International Conference on Machine Learning 3165\u20133176 (2020)."},{"key":"6221_CR80","unstructured":"Fuchs, F. et al. SE(3)-transformers: 3D roto-translation equivariant attention networks. In Advances in Neural Information Processing Systems 33, 1970-1981 (2020)."},{"key":"6221_CR81","unstructured":"Zaheer, M. et al. Deep sets. In Advances in Neural Information Processing Systems 30, 3391\u20133401 (2017). This paper is an early study that explores the use of deep neural architectures on set data, which consists of an unordered list of elements."},{"key":"6221_CR82","unstructured":"Cohen, T. S. et al. Spherical CNNs. In International Conference on Learning Representations (2018)."},{"key":"6221_CR83","unstructured":"Gordon, J. et al. Permutation equivariant models for compositional generalization in language. In International Conference on Learning Representations (2019)."},{"key":"6221_CR84","unstructured":"Finzi, M., Welling, M. & Wilson, A. G. A practical method for constructing equivariant multilayer perceptrons for arbitrary matrix groups. In International Conference on Machine Learning 3318\u20133328 (2021)."},{"key":"6221_CR85","doi-asserted-by":"publisher","first-page":"716","DOI":"10.1016\/j.cell.2018.05.061","volume":"174","author":"DV Dijk","year":"2018","unstructured":"Dijk, D. V. et al. Recovering gene interactions from single-cell data using data diffusion. Cell 174, 716\u2013729 (2018).","journal-title":"Cell"},{"key":"6221_CR86","doi-asserted-by":"publisher","first-page":"184","DOI":"10.1038\/s41592-019-0666-6","volume":"17","author":"P Gainza","year":"2020","unstructured":"Gainza, P. et al. Deciphering interaction fingerprints from protein molecular surfaces using geometric deep learning. Nat. Methods 17, 184\u2013192 (2020).","journal-title":"Nat. Methods"},{"key":"6221_CR87","doi-asserted-by":"publisher","first-page":"351","DOI":"10.1038\/s41586-021-03382-w","volume":"593","author":"PW Hatfield","year":"2021","unstructured":"Hatfield, P. W. et al. The data-driven future of high-energy-density physics. Nature 593, 351\u2013361 (2021).","journal-title":"Nature"},{"key":"6221_CR88","doi-asserted-by":"publisher","first-page":"448","DOI":"10.1038\/s41567-020-0842-8","volume":"16","author":"V Bapst","year":"2020","unstructured":"Bapst, V. et al. Unveiling the predictive power of static structure in glassy systems. Nat. Phys. 16, 448\u2013454 (2020).","journal-title":"Nat. Phys."},{"key":"6221_CR89","doi-asserted-by":"publisher","first-page":"254","DOI":"10.1038\/s41587-021-01034-y","volume":"40","author":"R Zhang","year":"2022","unstructured":"Zhang, R., Zhou, T. & Ma, J. Multiscale and integrative single-cell Hi-C analysis with Higashi. Nat. Biotechnol. 40, 254\u2013261 (2022).","journal-title":"Nat. Biotechnol."},{"key":"6221_CR90","doi-asserted-by":"publisher","first-page":"623","DOI":"10.1038\/s41586-021-04278-5","volume":"601","author":"S-J Sammut","year":"2022","unstructured":"Sammut, S.-J. et al. Multi-omic machine learning predictor of breast cancer therapy response. Nature 601, 623\u2013629 (2022).","journal-title":"Nature"},{"key":"6221_CR91","doi-asserted-by":"crossref","unstructured":"DeZoort, G. et al. Graph neural networks at the Large Hadron Collider. Nat. Rev. Phys. 5, 281\u2013303 (2023).","DOI":"10.1038\/s42254-023-00569-0"},{"key":"6221_CR92","unstructured":"Liu, S. et al. Pre-training molecular graph representation with 3D geometry. In International Conference on Learning Representations (2022)."},{"key":"6221_CR93","doi-asserted-by":"publisher","first-page":"85","DOI":"10.1038\/nature24471","volume":"551","author":"The LIGO Scientific Collaboration.","year":"2017","unstructured":"The LIGO Scientific Collaboration. et al. A gravitational-wave standard siren measurement of the Hubble constant. Nature 551, 85\u201388 (2017).","journal-title":"Nature"},{"key":"6221_CR94","doi-asserted-by":"publisher","first-page":"195","DOI":"10.1038\/s41586-019-0912-1","volume":"566","author":"M Reichstein","year":"2019","unstructured":"Reichstein, M. et al. Deep learning and process understanding for data-driven Earth system science. Nature 566, 195\u2013204 (2019).","journal-title":"Nature"},{"key":"6221_CR95","doi-asserted-by":"crossref","unstructured":"Goenka, S. D. et al. Accelerated identification of disease-causing variants with ultra-rapid nanopore genome sequencing. Nat. Biotechnol. 40, 1035\u20131041 (2022).","DOI":"10.1038\/s41587-022-01221-5"},{"key":"6221_CR96","doi-asserted-by":"crossref","unstructured":"Bengio, Y. et al. Greedy layer-wise training of deep networks. In Advances in Neural Information Processing Systems 19, 153\u2013160 (2006).","DOI":"10.7551\/mitpress\/7503.003.0024"},{"key":"6221_CR97","doi-asserted-by":"publisher","first-page":"1527","DOI":"10.1162\/neco.2006.18.7.1527","volume":"18","author":"GE Hinton","year":"2006","unstructured":"Hinton, G. E., Osindero, S. & Teh, Y.-W. A fast learning algorithm for deep belief nets. Neural Comput. 18, 1527\u20131554 (2006).","journal-title":"Neural Comput."},{"key":"6221_CR98","doi-asserted-by":"publisher","first-page":"255","DOI":"10.1126\/science.aaa8415","volume":"349","author":"MI Jordan","year":"2015","unstructured":"Jordan, M. I. & Mitchell, T. M. Machine learning: trends, perspectives, and prospects. Science 349, 255\u2013260 (2015).","journal-title":"Science"},{"key":"6221_CR99","unstructured":"Devlin, J. et al. BERT: pre-training of deep bidirectional transformers for language understanding. In North American Chapter of the Association for Computational Linguistics 4171\u20134186 (2019)."},{"key":"6221_CR100","doi-asserted-by":"crossref","unstructured":"Rives, A. et al. Biological structure and function emerge from scaling unsupervised learning to 250 million protein sequences. Proc. Natl Acad. Sci. USA 118, e2016239118 (2021).","DOI":"10.1073\/pnas.2016239118"},{"key":"6221_CR101","unstructured":"Elnaggar, A. et al. ProtTrans: rowards cracking the language of lifes code through self-supervised deep learning and high performance computing. In IEEE Transactions on Pattern Analysis and Machine Intelligence (2021)."},{"key":"6221_CR102","doi-asserted-by":"publisher","first-page":"284","DOI":"10.1126\/science.abd7331","volume":"371","author":"B Hie","year":"2021","unstructured":"Hie, B. et al. Learning the language of viral evolution and escape. Science 371, 284\u2013288 (2021).This paper modeled viral escape with machine learning algorithms originally developed for human natural language.","journal-title":"Science"},{"key":"6221_CR103","doi-asserted-by":"publisher","first-page":"389","DOI":"10.1038\/s41592-021-01100-y","volume":"18","author":"S Biswas","year":"2021","unstructured":"Biswas, S. et al. Low-N protein engineering with data-efficient deep learning. Nat. Methods 18, 389\u2013396 (2021).","journal-title":"Nat. Methods"},{"key":"6221_CR104","doi-asserted-by":"crossref","unstructured":"Ferruz, N. & H\u00f6cker, B. Controllable protein design with language models. Nat. Mach. Intell. 4, 521\u2013532 (2022).","DOI":"10.1038\/s42256-022-00499-z"},{"key":"6221_CR105","doi-asserted-by":"crossref","unstructured":"Hsu, C. et al. Learning inverse folding from millions of predicted structures. In International Conference on Machine Learning 8946\u20138970 (2022).","DOI":"10.1101\/2022.04.10.487779"},{"key":"6221_CR106","doi-asserted-by":"publisher","first-page":"871","DOI":"10.1126\/science.abj8754","volume":"373","author":"M Baek","year":"2021","unstructured":"Baek, M. et al. Accurate prediction of protein structures and interactions using a three-track neural network. Science 373, 871\u2013876 (2021). Inspired by AlphaFold2, this study reported RoseTTAFold, a novel three-track neural module capable of simultaneously processing protein\u2019s sequence, distance and coordinates.","journal-title":"Science"},{"key":"6221_CR107","doi-asserted-by":"publisher","first-page":"31","DOI":"10.1021\/ci00057a005","volume":"28","author":"D Weininger","year":"1988","unstructured":"Weininger, D. SMILES, a chemical language and information system. 1. Introduction to methodology and encoding rules. J. Chem. Inf. Comput. Sci. 28, 31\u201336 (1988).","journal-title":"J. Chem. Inf. Comput. Sci."},{"key":"6221_CR108","doi-asserted-by":"publisher","first-page":"1523","DOI":"10.1021\/acscentsci.9b00476","volume":"5","author":"T-S Lin","year":"2019","unstructured":"Lin, T.-S. et al. BigSMILES: a structurally-based line notation for describing macromolecules. ACS Cent. Sci. 5, 1523\u20131531 (2019).","journal-title":"ACS Cent. Sci."},{"key":"6221_CR109","doi-asserted-by":"crossref","unstructured":"Krenn, M. et al. SELFIES and the future of molecular string representations. Patterns 3, 100588 (2022).","DOI":"10.1016\/j.patter.2022.100588"},{"key":"6221_CR110","doi-asserted-by":"publisher","first-page":"3293","DOI":"10.1038\/s41467-022-30839-x","volume":"13","author":"D Flam-Shepherd","year":"2022","unstructured":"Flam-Shepherd, D., Zhu, K. & Aspuru-Guzik, A. Language models can learn complex molecular distributions. Nat. Commun. 13, 3293 (2022).","journal-title":"Nat. Commun."},{"key":"6221_CR111","doi-asserted-by":"publisher","first-page":"759","DOI":"10.1038\/s42256-021-00368-1","volume":"3","author":"MA Skinnider","year":"2021","unstructured":"Skinnider, M. A. et al. Chemical language models enable navigation in sparsely populated chemical space. Nat. Mach. Intell. 3, 759\u2013770 (2021).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR112","unstructured":"Chithrananda, S., Grand, G. & Ramsundar, B. ChemBERTa: large-scale self-supervised pretraining for molecular property prediction. In Machine Learning for Molecules Workshop at NeurIPS (2020)."},{"key":"6221_CR113","doi-asserted-by":"publisher","first-page":"3316","DOI":"10.1039\/C9SC05704H","volume":"11","author":"P Schwaller","year":"2020","unstructured":"Schwaller, P. et al. Predicting retrosynthetic pathways using transformer-based models and a hyper-graph exploration strategy. Chem. Sci. 11, 3316\u20133325 (2020).","journal-title":"Chem. Sci."},{"key":"6221_CR114","doi-asserted-by":"publisher","first-page":"5575","DOI":"10.1038\/s41467-020-19266-y","volume":"11","author":"IV Tetko","year":"2020","unstructured":"Tetko, I. V. et al. State-of-the-art augmented NLP transformer models for direct and single-step retrosynthesis. Nat. Commun. 11, 5575 (2020).","journal-title":"Nat. Commun."},{"key":"6221_CR115","doi-asserted-by":"publisher","first-page":"144","DOI":"10.1038\/s42256-020-00284-w","volume":"3","author":"P Schwaller","year":"2021","unstructured":"Schwaller, P. et al. Mapping the space of chemical reactions using attention-based neural networks. Nat. Mach. Intell. 3, 144\u2013152 (2021).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR116","doi-asserted-by":"publisher","first-page":"1695","DOI":"10.1038\/s41467-021-21895-w","volume":"12","author":"DP Kov\u00e1cs","year":"2021","unstructured":"Kov\u00e1cs, D. P., McCorkindale, W. & Lee, A. A. Quantitative interpretation explains machine learning models for chemical reaction prediction and uncovers bias. Nat. Commun. 12, 1695 (2021).","journal-title":"Nat. Commun."},{"key":"6221_CR117","doi-asserted-by":"publisher","first-page":"4874","DOI":"10.1038\/s41467-020-18671-7","volume":"11","author":"G Pesciullesi","year":"2020","unstructured":"Pesciullesi, G. et al. Transfer learning enables the molecular transformer to predict regio-and stereoselective reactions on carbohydrates. Nat. Commun. 11, 4874 (2020).","journal-title":"Nat. Commun."},{"key":"6221_CR118","unstructured":"Vaswani, A. et al. Attention is all you need. In Advances in Neural Information Processing Systems 30, 5998\u20136008 (2017). This paper introduced the transformer, a modern neural network architecture that can process sequential data in parallel, revolutionizing natural language processing and sequence modeling."},{"key":"6221_CR119","doi-asserted-by":"publisher","first-page":"3952","DOI":"10.1038\/s41467-020-17591-w","volume":"11","author":"SM Mousavi","year":"2020","unstructured":"Mousavi, S. M. et al. Earthquake transformer\u2014an attentive deep-learning model for simultaneous earthquake detection and phase picking. Nat. Commun. 11, 3952 (2020).","journal-title":"Nat. Commun."},{"key":"6221_CR120","doi-asserted-by":"publisher","first-page":"1196","DOI":"10.1038\/s41592-021-01252-x","volume":"18","author":"\u017d Avsec","year":"2021","unstructured":"Avsec, \u017d. et al. Effective gene expression prediction from sequence by integrating long-range interactions. Nat. Methods 18, 1196\u20131203 (2021).","journal-title":"Nat. Methods"},{"key":"6221_CR121","doi-asserted-by":"crossref","unstructured":"Meier, J. et al. Language models enable zero-shot prediction of the effects of mutations on protein function. In Advances in Neural Information Processing Systems 34, 29287\u201329303 (2021).","DOI":"10.1101\/2021.07.09.450648"},{"key":"6221_CR122","unstructured":"Kamienny, P.-A. et al. End-to-end symbolic regression with transformers. In Advances in Neural Information Processing Systems 35, 10269\u201310281 (2022)."},{"key":"6221_CR123","unstructured":"Jaegle, A. et al. Perceiver: general perception with iterative attention. In International Conference on Machine Learning 4651\u20134664 (2021)."},{"key":"6221_CR124","unstructured":"Chen, L. et al. Decision transformer: reinforcement learning via sequence modeling. In Advances in Neural Information Processing Systems 34, 15084\u201315097 (2021)."},{"key":"6221_CR125","unstructured":"Dosovitskiy, A. et al. An image is worth 16x16 words: transformers for image recognition at scale. In International Conference on Learning Representations (2020)."},{"key":"6221_CR126","unstructured":"Choromanski, K. et al. Rethinking attention with performers. In International Conference on Learning Representations (2021)."},{"key":"6221_CR127","unstructured":"Li, Z. et al. Fourier neural operator for parametric partial differential equations. In International Conference on Learning Representations (2021)."},{"key":"6221_CR128","unstructured":"Kovachki, N. et al. Neural operator: learning maps between function spaces. J. Mach. Learn. Res. 24, 1\u201397 (2023)."},{"key":"6221_CR129","doi-asserted-by":"publisher","first-page":"1","DOI":"10.1017\/S0007087400001813","volume":"2","author":"JL Russell","year":"1964","unstructured":"Russell, J. L. Kepler\u2019s laws of planetary motion: 1609\u20131666. Br. J. Hist. Sci. 2, 1\u201324 (1964).","journal-title":"Br. J. Hist. Sci."},{"key":"6221_CR130","doi-asserted-by":"crossref","unstructured":"Huang, K. et al. Artificial intelligence foundation for therapeutic science. Nat. Chem. Biol. 18, 1033\u20131036 (2022).","DOI":"10.1038\/s41589-022-01131-2"},{"key":"6221_CR131","doi-asserted-by":"publisher","first-page":"eaav6971","DOI":"10.1126\/sciadv.aav6971","volume":"6","author":"R Guimer\u00e0","year":"2020","unstructured":"Guimer\u00e0, R. et al. A Bayesian machine scientist to aid in the solution of challenging scientific problems. Sci. Adv. 6, eaav6971 (2020).","journal-title":"Sci. Adv."},{"key":"6221_CR132","doi-asserted-by":"publisher","unstructured":"Liu, G. et al. Deep learning-guided discovery of an antibiotic targeting Acinetobacter baumannii. Nat. Chem. Biol. https:\/\/doi.org\/10.1038\/s41589-023-01349-8 (2023).","DOI":"10.1038\/s41589-023-01349-8"},{"key":"6221_CR133","doi-asserted-by":"publisher","first-page":"1120","DOI":"10.1038\/nmat4717","volume":"15","author":"R G\u00f3mez-Bombarelli","year":"2016","unstructured":"G\u00f3mez-Bombarelli, R. et al. Design of efficient molecular organic light-emitting diodes by a high-throughput virtual screening and experimental approach. Nat. Mater. 15, 1120\u20131127 (2016). This paper proposes using a black-box AI predictor to accelerate high-throughput screening of molecules in materials science.","journal-title":"Nat. Mater."},{"key":"6221_CR134","doi-asserted-by":"publisher","first-page":"452","DOI":"10.1038\/s41586-021-04220-9","volume":"601","author":"AA Sadybekov","year":"2022","unstructured":"Sadybekov, A. A. et al. Synthon-based ligand discovery in virtual libraries of over 11 billion compounds. Nature 601, 452\u2013459 (2022).","journal-title":"Nature"},{"key":"6221_CR135","doi-asserted-by":"publisher","first-page":"483","DOI":"10.1038\/s41586-022-04998-2","volume":"606","author":"The NNPDF Collaboration","year":"2022","unstructured":"The NNPDF Collaboration Evidence for intrinsic charm quarks in the proton. Nature 606, 483\u2013487 (2022).","journal-title":"Nature"},{"key":"6221_CR136","doi-asserted-by":"publisher","first-page":"7866","DOI":"10.1039\/D0SC06805E","volume":"12","author":"DE Graff","year":"2021","unstructured":"Graff, D. E., Shakhnovich, E. I. & Coley, C. W. Accelerating high-throughput virtual screening through molecular pool-based active learning. Chem. Sci. 12, 7866\u20137881 (2021).","journal-title":"Chem. Sci."},{"key":"6221_CR137","doi-asserted-by":"publisher","first-page":"513","DOI":"10.1021\/acscentsci.0c00026","volume":"6","author":"JP Janet","year":"2020","unstructured":"Janet, J. P. et al. Accurate multiobjective design in a space of millions of transition metal complexes with neural-network-driven efficient global optimization. ACS Cent. Sci. 6, 513\u2013524 (2020).","journal-title":"ACS Cent. Sci."},{"key":"6221_CR138","unstructured":"Bacon, F. Novum Organon Vol. 1620 (2000)."},{"key":"6221_CR139","doi-asserted-by":"publisher","first-page":"81","DOI":"10.1126\/science.1165893","volume":"324","author":"M Schmidt","year":"2009","unstructured":"Schmidt, M. & Lipson, H. Distilling free-form natural laws from experimental data. Science 324, 81\u201385 (2009).","journal-title":"Science"},{"key":"6221_CR140","unstructured":"Petersen, B. K. et al. Deep symbolic regression: recovering mathematical expressions from data via risk-seeking policy gradients. In International Conference on Learning Representations (2020)."},{"key":"6221_CR141","doi-asserted-by":"publisher","first-page":"1038","DOI":"10.1038\/s41587-019-0224-x","volume":"37","author":"A Zhavoronkov","year":"2019","unstructured":"Zhavoronkov, A. et al. Deep learning enables rapid identification of potent DDR1 kinase inhibitors. Nat. Biotechnol. 37, 1038\u20131040 (2019). This paper describes a reinforcement-learning algorithm for navigating molecular combinatorial spaces, and it validates generated molecules using wet-lab experiments.","journal-title":"Nat. Biotechnol."},{"key":"6221_CR142","doi-asserted-by":"publisher","first-page":"10752","DOI":"10.1038\/s41598-019-47148-x","volume":"9","author":"Z Zhou","year":"2019","unstructured":"Zhou, Z. et al. Optimization of molecules via deep reinforcement learning. Sci. Rep. 9, 10752 (2019).","journal-title":"Sci. Rep."},{"key":"6221_CR143","unstructured":"You, J. et al. Graph convolutional policy network for goal-directed molecular graph generation. In Advances in Neural Information Processing Systems 31, 6412\u20136422 (2018)."},{"key":"6221_CR144","unstructured":"Bengio, Y. et al. GFlowNet foundations. Preprint at https:\/\/arxiv.org\/abs\/2111.09266 (2021). This paper describes a generative flow network that generates objects by sampling them from a distribution optimized for drug design."},{"key":"6221_CR145","unstructured":"Jain, M. et al. Biological sequence design with GFlowNets. In International Conference on Machine Learning 9786\u20139801 (2022)."},{"key":"6221_CR146","unstructured":"Malkin, N. et al. Trajectory balance: improved credit assignment in GFlowNets. In Advances in Neural Information Processing Systems 35, 5955\u20135967 (2022)."},{"key":"6221_CR147","doi-asserted-by":"publisher","first-page":"1872","DOI":"10.1038\/s41467-020-15798-5","volume":"11","author":"O Borkowski","year":"2020","unstructured":"Borkowski, O. et al. Large scale active-learning-guided exploration for in vitro protein production optimization. Nat. Commun. 11, 1872 (2020). This study introduced a dynamic programming approach to determine the optimal locations and capacities of hydropower dams in the Amazon Basin, balancing between energy production and environmental impact.","journal-title":"Nat. Commun."},{"key":"6221_CR148","doi-asserted-by":"publisher","first-page":"753","DOI":"10.1126\/science.abj4017","volume":"375","author":"AS Flecker","year":"2022","unstructured":"Flecker, A. S. et al. Reducing adverse impacts of Amazon hydropower expansion. Science 375, 753\u2013760 (2022).This study introduced a dynamic programming approach to determine the optimal locations and capacities of hydropower dams in the Amazon basin, achieving a balance between the benefits of energy production and the potential environmental impacts.","journal-title":"Science"},{"key":"6221_CR149","unstructured":"Pion-Tonachini, L. et al. Learning from learning machines: a new generation of AI technology to meet the needs of science. Preprint at https:\/\/arxiv.org\/abs\/2111.13786 (2021)."},{"key":"6221_CR150","unstructured":"Kusner, M. J., Paige, B. & Hern\u00e1ndez-Lobato, J. M. Grammar variational autoencoder. In International Conference on Machine Learning 1945\u20131954 (2017). This paper describes a grammar variational autoencoder that generates novel symbolic laws and drug molecules."},{"key":"6221_CR151","doi-asserted-by":"publisher","first-page":"3932","DOI":"10.1073\/pnas.1517384113","volume":"113","author":"SL Brunton","year":"2016","unstructured":"Brunton, S. L., Proctor, J. L. & Kutz, J. N. Discovering governing equations from data by sparse identification of nonlinear dynamical systems. Proc. Natl Acad. Sci. USA 113, 3932\u20133937 (2016).","journal-title":"Proc. Natl Acad. Sci. USA"},{"key":"6221_CR152","doi-asserted-by":"publisher","first-page":"180201","DOI":"10.1103\/PhysRevLett.128.180201","volume":"128","author":"Z Liu","year":"2022","unstructured":"Liu, Z. & Tegmark, M. Machine learning hidden symmetries. Phys. Rev. Lett. 128, 180201 (2022).","journal-title":"Phys. Rev. Lett."},{"key":"6221_CR153","doi-asserted-by":"publisher","first-page":"112","DOI":"10.1038\/s41567-021-01425-7","volume":"18","author":"H Gabbard","year":"2022","unstructured":"Gabbard, H. et al. Bayesian parameter estimation using conditional variational autoencoders for gravitational-wave astronomy. Nat. Phys. 18, 112\u2013117 (2022).","journal-title":"Nat. Phys."},{"key":"6221_CR154","doi-asserted-by":"publisher","first-page":"812","DOI":"10.1038\/s42256-021-00384-1","volume":"3","author":"D Chen","year":"2021","unstructured":"Chen, D. et al. Automating crystal-structure phase mapping by combining deep learning with constraint reasoning. Nat. Mach. Intell. 3, 812\u2013822 (2021).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR155","doi-asserted-by":"crossref","unstructured":"G\u00f3mez-Bombarelli, R. et al. Automatic chemical design using a data-driven continuous representation of molecules. ACS Cent. Sci. 4, 268\u2013276 (2018).","DOI":"10.1021\/acscentsci.7b00572"},{"key":"6221_CR156","doi-asserted-by":"publisher","first-page":"547","DOI":"10.1038\/s41586-021-04184-w","volume":"600","author":"I Anishchenko","year":"2021","unstructured":"Anishchenko, I. et al. De novo protein design by deep network hallucination. Nature 600, 547\u2013552 (2021).","journal-title":"Nature"},{"key":"6221_CR157","unstructured":"Fu, T. et al. Differentiable scaffolding tree for molecular optimization. In International Conference on Learning Representations (2021)."},{"key":"6221_CR158","doi-asserted-by":"publisher","first-page":"360","DOI":"10.1126\/science.aat2663","volume":"361","author":"B Sanchez-Lengeling","year":"2018","unstructured":"Sanchez-Lengeling, B. & Aspuru-Guzik, A. Inverse molecular design using machine learning: generative models for matter engineering. Science 361, 360\u2013365 (2018).","journal-title":"Science"},{"key":"6221_CR159","unstructured":"Huang, K. et al. Therapeutics Data Commons: machine learning datasets and tasks for drug discovery and development. In NeurIPS Datasets and Benchmarks (2021). This study describes an initiative with open AI models, datasets and education programmes to facilitate advances in therapeutic science across all stages of drug discovery and development."},{"key":"6221_CR160","doi-asserted-by":"publisher","first-page":"664","DOI":"10.1038\/nj7238-664a","volume":"458","author":"A Dance","year":"2009","unstructured":"Dance, A. Lab hazard. Nature 458, 664\u2013665 (2009).","journal-title":"Nature"},{"key":"6221_CR161","doi-asserted-by":"publisher","first-page":"604","DOI":"10.1038\/nature25978","volume":"555","author":"MHS Segler","year":"2018","unstructured":"Segler, M. H. S., Preuss, M. & Waller, M. P. Planning chemical syntheses with deep neural networks and symbolic AI. Nature 555, 604\u2013610 (2018). This paper describes an approach that combines deep neural networks with Monte Carlo tree search to plan chemical synthesis.","journal-title":"Nature"},{"key":"6221_CR162","doi-asserted-by":"publisher","first-page":"1075","DOI":"10.1038\/s41467-022-28736-4","volume":"13","author":"W Gao","year":"2022","unstructured":"Gao, W., Raghavan, P. & Coley, C. W. Autonomous platforms for data-driven organic synthesis. Nat. Commun. 13, 1075 (2022).","journal-title":"Nat. Commun."},{"key":"6221_CR163","doi-asserted-by":"publisher","first-page":"5966","DOI":"10.1038\/s41467-020-19597-w","volume":"11","author":"AG Kusne","year":"2020","unstructured":"Kusne, A. G. et al. On-the-fly closed-loop materials discovery via Bayesian active learning. Nat. Commun. 11, 5966 (2020).","journal-title":"Nat. Commun."},{"key":"6221_CR164","doi-asserted-by":"publisher","first-page":"642","DOI":"10.1038\/s41578-021-00282-3","volume":"6","author":"AJ Gormley,","year":"2021","unstructured":"Gormley,A. J. & Webb, M. A. Machine learning in combinatorial polymer chemistry. Nat. Rev. Mater. 6, 642\u2013644 (2021).","journal-title":"Nat. Rev. Mater."},{"key":"6221_CR165","doi-asserted-by":"publisher","first-page":"eabg4930","DOI":"10.1126\/sciadv.abg4930","volume":"7","author":"S Ament","year":"2021","unstructured":"Ament, S. et al. Autonomous materials synthesis via hierarchical active learning of nonequilibrium phase diagrams. Sci. Adv. 7, eabg4930 (2021).","journal-title":"Sci. Adv."},{"key":"6221_CR166","doi-asserted-by":"publisher","first-page":"414","DOI":"10.1038\/s41586-021-04301-9","volume":"602","author":"J Degrave","year":"2022","unstructured":"Degrave, J. et al. Magnetic control of tokamak plasmas through deep reinforcement learning. Nature 602, 414\u2013419 (2022).This paper describes an approach for controlling tokamak plasmas, using a reinforcement-learning agent to command-control coils and satisfy physical and operational constraints.","journal-title":"Nature"},{"key":"6221_CR167","doi-asserted-by":"publisher","first-page":"1221","DOI":"10.1073\/pnas.1714936115","volume":"115","author":"AA Melnikov","year":"2018","unstructured":"Melnikov, A. A. et al. Active learning machine learns to create new quantum experiments. Proc. Natl Acad. Sci. USA 115, 1221\u20131226 (2018).","journal-title":"Proc. Natl Acad. Sci. USA"},{"key":"6221_CR168","doi-asserted-by":"publisher","first-page":"3192","DOI":"10.1039\/C6SC05720A","volume":"8","author":"JS Smith","year":"2017","unstructured":"Smith, J. S., Isayev, O. & Roitberg, A. E. ANI-1: an extensible neural network potential with DFT accuracy at force field computational cost. Chem. Sci. 8, 3192\u20133203 (2017).","journal-title":"Chem. Sci."},{"key":"6221_CR169","doi-asserted-by":"publisher","first-page":"20","DOI":"10.1038\/s43588-021-00173-1","volume":"2","author":"D Wang","year":"2022","unstructured":"Wang, D. et al. Efficient sampling of high-dimensional free energy landscapes using adaptive reinforced dynamics. Nat. Comput. Sci. 2, 20\u201329 (2022).This paper describes a neural network for reliable uncertainty estimations in molecular dynamics, enabling efficient sampling of high-dimensional free energy landscapes.","journal-title":"Nat. Comput. Sci."},{"key":"6221_CR170","doi-asserted-by":"publisher","first-page":"125","DOI":"10.1038\/s41524-019-0261-5","volume":"5","author":"W Wang","year":"2019","unstructured":"Wang, W. & G\u00f3mez-Bombarelli, R. Coarse-graining auto-encoders for molecular dynamics. npj Comput. Mater. 5, 125 (2019).","journal-title":"npj Comput. Mater."},{"key":"6221_CR171","doi-asserted-by":"publisher","first-page":"891","DOI":"10.1038\/s41557-020-0544-y","volume":"12","author":"J Hermann","year":"2020","unstructured":"Hermann, J., Sch\u00e4tzle, Z. & No\u00e9, F. Deep-neural-network solution of the electronic Schr\u00f6dinger equation. Nat. Chem. 12, 891\u2013897 (2020).This paper describes a method to learn the wavefunction of quantum systems using deep neural networks in conjunction with variational quantum Monte Carlo.","journal-title":"Nat. Chem."},{"key":"6221_CR172","doi-asserted-by":"publisher","first-page":"602","DOI":"10.1126\/science.aag2302","volume":"355","author":"G Carleo","year":"2017","unstructured":"Carleo, G. & Troyer, M. Solving the quantum many-body problem with artificial neural networks. Science 355, 602\u2013606 (2017).","journal-title":"Science"},{"key":"6221_CR173","doi-asserted-by":"publisher","first-page":"422","DOI":"10.1038\/s42254-021-00314-5","volume":"3","author":"G Em Karniadakis","year":"2021","unstructured":"Em Karniadakis, G. et al. Physics-informed machine learning. Nat. Rev. Phys. 3, 422\u2013440 (2021).","journal-title":"Nat. Rev. Phys."},{"key":"6221_CR174","unstructured":"Li, Z. et al. Physics-informed neural operator for learning partial differential equations. Preprint at https:\/\/arxiv.org\/abs\/2111.03794 (2021)."},{"key":"6221_CR175","doi-asserted-by":"crossref","unstructured":"Kochkov, D. et al. Machine learning\u2013accelerated computational fluid dynamics. Proc. Natl Acad. Sci. USA 118, e2101784118 (2021). This paper describes an approach to accelerating computational fluid dynamics by training a neural network to interpolate from coarse to fine grids and generalize to varying forcing functions and Reynolds numbers.","DOI":"10.1073\/pnas.2101784118"},{"key":"6221_CR176","doi-asserted-by":"publisher","first-page":"8098","DOI":"10.1021\/acs.jpca.1c05102","volume":"125","author":"W Ji","year":"2021","unstructured":"Ji, W. et al. Stiff-PINN: physics-informed neural network for stiff chemical kinetics. J. Phys. Chem. A 125, 8098\u20138106 (2021).","journal-title":"J. Phys. Chem. A"},{"key":"6221_CR177","doi-asserted-by":"publisher","first-page":"10685","DOI":"10.1109\/TGRS.2020.3039165","volume":"59","author":"JD Smith","year":"2020","unstructured":"Smith, J. D., Azizzadenesheli, K. & Ross, Z. E. EikoNet: solving the Eikonal equation with deep neural networks. IEEE Trans. Geosci. Remote Sens. 59, 10685\u201310696 (2020).","journal-title":"IEEE Trans. Geosci. Remote Sens."},{"key":"6221_CR178","doi-asserted-by":"publisher","first-page":"104833","DOI":"10.1016\/j.cageo.2021.104833","volume":"155","author":"UB Waheed","year":"2021","unstructured":"Waheed, U. B. et al. PINNeik: Eikonal solution using physics-informed neural networks. Comput. Geosci. 155, 104833 (2021).","journal-title":"Comput. Geosci."},{"key":"6221_CR179","unstructured":"Chen, R. T. Q. et al. Neural ordinary differential equations. In Advances in Neural Information Processing Systems 31, 6572\u20136583 (2018). This paper established a connection between neural networks and differential equations by introducing the adjoint method to learn continuous-time dynamical systems from data, replacing backpropagation."},{"key":"6221_CR180","doi-asserted-by":"publisher","first-page":"686","DOI":"10.1016\/j.jcp.2018.10.045","volume":"378","author":"M Raissi","year":"2019","unstructured":"Raissi, M., Perdikaris, P. & Karniadakis, G. E. Physics-informed neural networks: a deep learning framework for solving forward and inverse problems involving nonlinear partial differential equations. J. Comput. Phys. 378, 686\u2013707 (2019). This paper describes a deep-learning approach for solving forwards and inverse problems in nonlinear partial differential equations and can find solutions to differential equations from data.","journal-title":"J. Comput. Phys."},{"key":"6221_CR181","doi-asserted-by":"publisher","first-page":"218","DOI":"10.1038\/s42256-021-00302-5","volume":"3","author":"L Lu","year":"2021","unstructured":"Lu, L. et al. Learning nonlinear operators via DeepONet based on the universal approximation theorem of operators. Nat. Mach. Intell. 3, 218\u2013229 (2021).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR182","unstructured":"Brandstetter, J., Worrall, D. & Welling, M. Message passing neural PDE solvers. In International Conference on Learning Representations (2022)."},{"key":"6221_CR183","doi-asserted-by":"crossref","unstructured":"No\u00e9, F. et al. Boltzmann generators: sampling equilibrium states of many-body systems with deep learning. Science 365, eaaw1147 (2019). This paper presents an efficient sampling algorithm using normalizing flows to simulate equilibrium states in many-body systems.","DOI":"10.1126\/science.aaw1147"},{"key":"6221_CR184","unstructured":"Rezende, D. & Mohamed, S. Variational inference with normalizing flows. In International Conference on Machine Learning 37, 1530\u20131538, (2015)."},{"key":"6221_CR185","unstructured":"Dinh, L., Sohl-Dickstein, J. & Bengio, S. Density estimation using real NVP. In International Conference on Learning Representations (2017)."},{"key":"6221_CR186","doi-asserted-by":"publisher","first-page":"032001","DOI":"10.1103\/PhysRevLett.126.032001","volume":"126","author":"KA Nicoli","year":"2021","unstructured":"Nicoli, K. A. et al. Estimation of thermodynamic observables in lattice field theories with deep generative models. Phys. Rev. Lett. 126, 032001 (2021).","journal-title":"Phys. Rev. Lett."},{"key":"6221_CR187","doi-asserted-by":"publisher","first-page":"121601","DOI":"10.1103\/PhysRevLett.125.121601","volume":"125","author":"G Kanwar","year":"2020","unstructured":"Kanwar, G. et al. Equivariant flow-based sampling for lattice gauge theory. Phys. Rev. Lett. 125, 121601 (2020).","journal-title":"Phys. Rev. Lett."},{"key":"6221_CR188","doi-asserted-by":"publisher","first-page":"e2109420119","DOI":"10.1073\/pnas.2109420119","volume":"119","author":"M Gabri\u00e9","year":"2022","unstructured":"Gabri\u00e9, M., Rotskoff, G. M. & Vanden-Eijnden, E. Adaptive Monte Carlo augmented with normalizing flows. Proc. Natl Acad. Sci. USA 119, e2109420119 (2022).","journal-title":"Proc. Natl Acad. Sci. USA"},{"key":"6221_CR189","doi-asserted-by":"crossref","unstructured":"Jasra, A., Holmes, C. C. & Stephens, D. A. Markov chain Monte Carlo methods and the label switching problem in Bayesian mixture modeling. Stat. Sci. 20, 50\u201367 (2005).","DOI":"10.1214\/088342305000000016"},{"key":"6221_CR190","unstructured":"Bengio, Y. et al. Better mixing via deep representations. In International Conference on Machine Learning 552\u2013560 (2013)."},{"key":"6221_CR191","doi-asserted-by":"publisher","first-page":"2930","DOI":"10.1214\/19-AOS1916","volume":"48","author":"E Pompe","year":"2020","unstructured":"Pompe, E., Holmes, C. & \u0141atuszy\u0144ski, K. A framework for adaptive MCMC targeting multimodal distributions. Ann. Stat. 48, 2930\u20132952 (2020).","journal-title":"Ann. Stat."},{"key":"6221_CR192","unstructured":"Townshend, R. J. L. et al. ATOM3D: tasks on molecules in three dimensions. In NeurIPS Datasets and Benchmarks (2021)."},{"key":"6221_CR193","doi-asserted-by":"publisher","first-page":"18820","DOI":"10.1021\/jacs.1c09820","volume":"143","author":"SM Kearnes","year":"2021","unstructured":"Kearnes, S. M. et al. The open reaction database. J. Am. Chem. Soc. 143, 18820\u201318826 (2021).","journal-title":"J. Am. Chem. Soc."},{"key":"6221_CR194","doi-asserted-by":"publisher","first-page":"6059","DOI":"10.1021\/acscatal.0c04525","volume":"11","author":"L Chanussot","year":"2021","unstructured":"Chanussot, L. et al. Open Catalyst 2020 (OC20) dataset and community challenges. ACS Catal. 11, 6059\u20136072 (2021).","journal-title":"ACS Catal."},{"key":"6221_CR195","doi-asserted-by":"publisher","first-page":"1096","DOI":"10.1021\/acs.jcim.8b00839","volume":"59","author":"N Brown","year":"2019","unstructured":"Brown, N. et al. GuacaMol: benchmarking models for de novo molecular design. J. Chem. Inf. Model. 59, 1096\u20131108 (2019).","journal-title":"J. Chem. Inf. Model."},{"key":"6221_CR196","unstructured":"Notin, P. et al. Tranception: protein fitness prediction with autoregressive transformers and inference-time retrieval. In International Conference on Machine Learning 16990\u201317017 (2022)."},{"key":"6221_CR197","doi-asserted-by":"crossref","unstructured":"Mitchell, M. et al. Model cards for model reporting. In Conference on Fairness, Accountability, and Transparency220\u2013229 (2019).","DOI":"10.1145\/3287560.3287596"},{"key":"6221_CR198","doi-asserted-by":"publisher","first-page":"86","DOI":"10.1145\/3458723","volume":"64","author":"T Gebru","year":"2021","unstructured":"Gebru, T. et al. Datasheets for datasets. Commun. ACM 64, 86\u201392 (2021).","journal-title":"Commun. ACM"},{"key":"6221_CR199","doi-asserted-by":"publisher","first-page":"1081","DOI":"10.1038\/s42256-021-00421-z","volume":"3","author":"X Bai","year":"2021","unstructured":"Bai, X. et al. Advancing COVID-19 diagnosis with privacy-preserving collaboration in artificial intelligence. Nat. Mach. Intell. 3, 1081\u20131089 (2021).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR200","doi-asserted-by":"publisher","first-page":"265","DOI":"10.1038\/s41586-021-03583-3","volume":"594","author":"S Warnat-Herresthal","year":"2021","unstructured":"Warnat-Herresthal, S. et al. Swarm learning for decentralized and confidential clinical machine learning. Nature 594, 265\u2013270 (2021).","journal-title":"Nature"},{"key":"6221_CR201","doi-asserted-by":"publisher","first-page":"347","DOI":"10.1126\/science.aat4807","volume":"362","author":"B Hie","year":"2018","unstructured":"Hie, B., Cho, H. & Berger, B. Realizing private and practical pharmacological collaboration. Science 362, 347\u2013350 (2018).","journal-title":"Science"},{"key":"6221_CR202","doi-asserted-by":"publisher","first-page":"172","DOI":"10.1126\/science.abo0058","volume":"377","author":"S Rohrbach","year":"2022","unstructured":"Rohrbach, S. et al. Digitization and validation of a chemical synthesis literature database in the ChemPU. Science 377, 172\u2013180 (2022).","journal-title":"Science"},{"key":"6221_CR203","doi-asserted-by":"publisher","first-page":"e2025581118","DOI":"10.1073\/pnas.2025581118","volume":"118","author":"DM Gysi","year":"2021","unstructured":"Gysi, D. M. et al. Network medicine framework for identifying drug-repurposing opportunities for COVID-19. Proc. Natl Acad. Sci. USA 118, e2025581118 (2021).","journal-title":"Proc. Natl Acad. Sci. USA"},{"key":"6221_CR204","doi-asserted-by":"publisher","first-page":"85","DOI":"10.1126\/science.1165620","volume":"324","author":"RD King","year":"2009","unstructured":"King, R. D. et al. The automation of science. Science 324, 85\u201389 (2009).","journal-title":"Science"},{"key":"6221_CR205","doi-asserted-by":"crossref","unstructured":"Mirdita, M. et al. ColabFold: making protein folding accessible to all. Nat. Methods 19, 679\u2013682 (2022).","DOI":"10.1038\/s41592-022-01488-1"},{"key":"6221_CR206","doi-asserted-by":"publisher","first-page":"2355","DOI":"10.1021\/acs.jctc.0c01343","volume":"17","author":"S Doerr","year":"2021","unstructured":"Doerr, S. et al. TorchMD: a deep learning framework for molecular simulations. J. Chem. Theory Comput. 17, 2355\u20132363 (2021).","journal-title":"J. Chem. Theory Comput."},{"key":"6221_CR207","unstructured":"Schoenholz, S. S. & Cubuk, E. D. JAX MD: a framework for differentiable physics. In Advances in Neural Information Processing Systems 33, 11428\u201311441 (2020)."},{"key":"6221_CR208","unstructured":"Peters, J., Janzing, D. & Sch\u00f6lkopf, B. Elements of Causal Inference: Foundations and Learning Algorithms (MIT Press, 2017)."},{"key":"6221_CR209","unstructured":"Bengio, Y. et al. A meta-transfer objective for learning to disentangle causal mechanisms. In International Conference on Learning Representations (2020)."},{"key":"6221_CR210","doi-asserted-by":"publisher","first-page":"612","DOI":"10.1109\/JPROC.2021.3058954","volume":"109","author":"B Sch\u00f6lkopf","year":"2021","unstructured":"Sch\u00f6lkopf, B. et al. Toward causal representation learning. Proc. IEEE 109, 612\u2013634 (2021).","journal-title":"Proc. IEEE"},{"key":"6221_CR211","doi-asserted-by":"crossref","unstructured":"Goyal, A. & Bengio, Y. Inductive biases for deep learning of higher-level cognition. Proc. R. Soc. A 478, 20210068 (2022).","DOI":"10.1098\/rspa.2021.0068"},{"key":"6221_CR212","unstructured":"Deleu, T. et al. Bayesian structure learning with generative flow networks. In Conference on Uncertainty in Artificial Intelligence 518\u2013528 (2022)."},{"key":"6221_CR213","doi-asserted-by":"publisher","first-page":"665","DOI":"10.1038\/s42256-020-00257-z","volume":"2","author":"R Geirhos","year":"2020","unstructured":"Geirhos, R. et al. Shortcut learning in deep neural networks. Nat. Mach. Intell. 2, 665\u2013673 (2020).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR214","unstructured":"Koh, P. W. et al. WILDS: a benchmark of in-the-wild distribution shifts. In International Conference on Machine Learning 5637\u20135664 (2021)."},{"key":"6221_CR215","unstructured":"Luo, Z. et al. Label efficient learning of transferable representations across domains and tasks. In Advances in Neural Information Processing Systems 30, 165\u2013177 (2017)."},{"key":"6221_CR216","doi-asserted-by":"crossref","unstructured":"Mahmood, R. et al. How much more data do I need? estimating requirements for downstream tasks. In IEEE Conference on Computer Vision and Pattern Recognition 275\u2013284 (2022).","DOI":"10.1109\/CVPR52688.2022.00037"},{"key":"6221_CR217","doi-asserted-by":"publisher","first-page":"23414","DOI":"10.1002\/anie.201909989","volume":"59","author":"CW Coley","year":"2020","unstructured":"Coley, C. W., Eyke, N. S. & Jensen, K. F. Autonomous discovery in the chemical sciences part II: outlook. Angew. Chem. Int. Ed. 59, 23414\u201323436 (2020).","journal-title":"Angew. Chem. Int. Ed."},{"key":"6221_CR218","doi-asserted-by":"publisher","first-page":"5714","DOI":"10.1021\/acs.jcim.0c00174","volume":"60","author":"W Gao","year":"2020","unstructured":"Gao, W. & Coley, C. W. The synthesizability of molecules proposed by generative models. J. Chem. Inf. Model. 60, 5714\u20135723 (2020).","journal-title":"J. Chem. Inf. Model."},{"key":"6221_CR219","doi-asserted-by":"publisher","first-page":"045003","DOI":"10.1103\/RevModPhys.91.045003","volume":"91","author":"R Kogler","year":"2019","unstructured":"Kogler, R. et al. Jet substructure at the Large Hadron Collider. Rev. Mod. Phys. 91, 045003 (2019).","journal-title":"Rev. Mod. Phys."},{"key":"6221_CR220","doi-asserted-by":"crossref","unstructured":"Acosta, J. N. et al. Multimodal biomedical AI. Nat. Med. 28, 1773\u20131784 (2022).","DOI":"10.1038\/s41591-022-01981-2"},{"key":"6221_CR221","unstructured":"Alayrac, J.-B. et al. Flamingo: a visual language model for few-shot learning. In Advances in Neural Information Processing Systems 35, 23716\u201323736 (2022)."},{"key":"6221_CR222","doi-asserted-by":"publisher","first-page":"348","DOI":"10.1038\/s41586-021-03922-4","volume":"598","author":"HA Elmarakeby","year":"2021","unstructured":"Elmarakeby, H. A. et al. Biologically informed deep neural network for prostate cancer discovery. Nature 598, 348\u2013352 (2021).","journal-title":"Nature"},{"key":"6221_CR223","doi-asserted-by":"publisher","first-page":"536","DOI":"10.1038\/s41586-021-04115-9","volume":"600","author":"Y Qin","year":"2021","unstructured":"Qin, Y. et al. A multi-scale map of cell structure fusing protein images and interactions. Nature 600, 536\u2013542 (2021).","journal-title":"Nature"},{"key":"6221_CR224","doi-asserted-by":"publisher","first-page":"622","DOI":"10.1016\/j.cels.2021.05.012","volume":"12","author":"LV Schaffer","year":"2021","unstructured":"Schaffer, L. V. & Ideker, T. Mapping the multiscale structure of biological systems. Cell Systems 12, 622\u2013635 (2021).","journal-title":"Cell Systems"},{"key":"6221_CR225","doi-asserted-by":"publisher","first-page":"e1379","DOI":"10.1002\/widm.1379","volume":"10","author":"G Stiglic","year":"2020","unstructured":"Stiglic, G. et al. Interpretability of machine learning-based prediction models in healthcare. Wiley Interdiscip. Rev. Data Min. Knowl. Discov. 10, e1379 (2020).","journal-title":"Wiley Interdiscip. Rev. Data Min. Knowl. Discov."},{"key":"6221_CR226","doi-asserted-by":"crossref","unstructured":"Erion, G. et al. A cost-aware framework for the development of AI models for healthcare applications. Nat. Biomed. Eng. 6, 1384\u20131398 (2022).","DOI":"10.1038\/s41551-022-00872-8"},{"key":"6221_CR227","doi-asserted-by":"publisher","first-page":"749","DOI":"10.1038\/s41551-018-0304-0","volume":"2","author":"SM Lundberg","year":"2018","unstructured":"Lundberg, S. M. et al. Explainable machine-learning predictions for the prevention of hypoxaemia during surgery. Nat. Biomed. Eng. 2, 749\u2013760 (2018).","journal-title":"Nat. Biomed. Eng."},{"key":"6221_CR228","unstructured":"Sanders, L. M. et al. Beyond low Earth orbit: biological research, artificial intelligence, and self-driving labs. Preprint at https:\/\/arxiv.org\/abs\/2112.12582 (2021)."},{"key":"6221_CR229","doi-asserted-by":"publisher","first-page":"2827","DOI":"10.1175\/MWR-D-18-0316.1","volume":"147","author":"DJ Gagne II","year":"2019","unstructured":"Gagne, D. J. II et al. Interpretable deep learning for spatial analysis of severe hailstorms. Mon. Weather Rev. 147, 2827\u20132845 (2019).","journal-title":"Mon. Weather Rev."},{"key":"6221_CR230","doi-asserted-by":"publisher","first-page":"206","DOI":"10.1038\/s42256-019-0048-x","volume":"1","author":"C Rudin","year":"2019","unstructured":"Rudin, C. Stop explaining black box machine learning models for high stakes decisions and use interpretable models instead. Nat. Mach. Intell. 1, 206\u2013215 (2019).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR231","unstructured":"Koh, P. W. & Liang, P. Understanding black-box predictions via influence functions. In International Conference on Machine Learning 1885\u20131894 (2017)."},{"key":"6221_CR232","unstructured":"Mirzasoleiman, B., Bilmes, J. & Leskovec, J. Coresets for data-efficient training of machine learning models. In International Conference on Machine Learning 6950\u20136960 (2020)."},{"key":"6221_CR233","unstructured":"Kim, B. et al. Interpretability beyond feature attribution: quantitative testing with concept activation vectors (TCAV). In International Conference on Machine Learning 2668\u20132677 (2018)."},{"key":"6221_CR234","doi-asserted-by":"publisher","first-page":"354","DOI":"10.1038\/nature24270","volume":"550","author":"D Silver","year":"2017","unstructured":"Silver, D. et al. Mastering the game of go without human knowledge. Nature 550, 354\u2013359 (2017).","journal-title":"Nature"},{"key":"6221_CR235","doi-asserted-by":"publisher","first-page":"3197","DOI":"10.1021\/acs.jcim.1c00619","volume":"61","author":"ZJ Baum","year":"2021","unstructured":"Baum, Z. J. et al. Artificial intelligence in chemistry: current trends and future directions. J. Chem. Inf. Model. 61, 3197\u20133212 (2021).","journal-title":"J. Chem. Inf. Model."},{"key":"6221_CR236","doi-asserted-by":"publisher","first-page":"1287","DOI":"10.1126\/science.aaw4399","volume":"363","author":"SG Finlayson","year":"2019","unstructured":"Finlayson, S. G. et al. Adversarial attacks on medical machine learning. Science 363, 1287\u20131289 (2019).","journal-title":"Science"},{"key":"6221_CR237","doi-asserted-by":"publisher","first-page":"189","DOI":"10.1038\/s42256-022-00465-9","volume":"4","author":"F Urbina","year":"2022","unstructured":"Urbina, F. et al. Dual use of artificial-intelligence-powered drug discovery. Nat. Mach. Intell. 4, 189\u2013191 (2022).","journal-title":"Nat. Mach. Intell."},{"key":"6221_CR238","doi-asserted-by":"publisher","first-page":"1320","DOI":"10.1038\/s41591-020-1041-y","volume":"26","author":"B Norgeot","year":"2020","unstructured":"Norgeot, B. et al. Minimum information about clinical artificial intelligence modeling: the MI-CLAIM checklist. Nat. Med. 26, 1320\u20131324 (2020).","journal-title":"Nat. Med."}],"updated-by":[{"DOI":"10.1038\/s41586-023-06559-7","type":"correction","label":"Correction","source":"publisher","updated":{"date-parts":[[2023,8,30]],"date-time":"2023-08-30T00:00:00Z","timestamp":1693353600000}}],"container-title":["Nature"],"original-title":[],"language":"en","link":[{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06221-2.pdf","content-type":"application\/pdf","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06221-2","content-type":"text\/html","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06221-2.pdf","content-type":"application\/pdf","content-version":"vor","intended-application":"similarity-checking"}],"deposited":{"date-parts":[[2023,8,31]],"date-time":"2023-08-31T03:04:55Z","timestamp":1693451095000},"score":1,"resource":{"primary":{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06221-2"}},"subtitle":[],"short-title":[],"issued":{"date-parts":[[2023,8,2]]},"references-count":238,"journal-issue":{"issue":"7972","published-print":{"date-parts":[[2023,8,3]]}},"alternative-id":["6221"],"URL":"https:\/\/doi.org\/10.1038\/s41586-023-06221-2","relation":{},"ISSN":["0028-0836","1476-4687"],"issn-type":[{"value":"0028-0836","type":"print"},{"value":"1476-4687","type":"electronic"}],"subject":[],"published":{"date-parts":[[2023,8,2]]},"assertion":[{"value":"30 March 2022","order":1,"name":"received","label":"Received","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"16 May 2023","order":2,"name":"accepted","label":"Accepted","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"2 August 2023","order":3,"name":"first_online","label":"First Online","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"30 August 2023","order":4,"name":"change_date","label":"Change Date","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"Correction","order":5,"name":"change_type","label":"Change Type","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"A Correction to this paper has been published:","order":6,"name":"change_details","label":"Change Details","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"https:\/\/doi.org\/10.1038\/s41586-023-06559-7","URL":"https:\/\/doi.org\/10.1038\/s41586-023-06559-7","order":7,"name":"change_details","label":"Change Details","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"The authors declare no competing interests.","order":1,"name":"Ethics","group":{"name":"EthicsHeading","label":"Competing interests"}}]}} | ||||
| \ No newline at end of file | |||||
added
research/verify_cache/https_api_crossref_org_works_10_1038_2Fs41586_023_06792_0
+1 −0
@@ -0,0 +1 @@ | |||||
| 1 | +{"status":"ok","message-type":"work","message-version":"1.0.0","message":{"indexed":{"date-parts":[[2026,10,29]],"date-time":"2026-10-29T12:45:43Z","timestamp":1793277943743,"version":"4.5.0"},"reference-count":52,"publisher":"Springer Science and Business Media LLC","issue":"7992","license":[{"start":{"date-parts":[[2023,12,20]],"date-time":"2023-12-20T00:00:00Z","timestamp":1703030400000},"content-version":"tdm","delay-in-days":0,"URL":"https:\/\/creativecommons.org\/licenses\/by\/4.0"},{"start":{"date-parts":[[2023,12,20]],"date-time":"2023-12-20T00:00:00Z","timestamp":1703030400000},"content-version":"vor","delay-in-days":0,"URL":"https:\/\/creativecommons.org\/licenses\/by\/4.0"}],"content-domain":{"domain":["link.springer.com"],"crossmark-restriction":false},"short-container-title":["Nature"],"published-print":{"date-parts":[[2023,12,21]]},"abstract":"<jats:title>Abstract<\/jats:title>\n <jats:p>\n Transformer-based large language models are making significant strides in various fields, such as natural language processing\n <jats:sup>1\u20135<\/jats:sup>\n , biology\n <jats:sup>6,7<\/jats:sup>\n , chemistry\n <jats:sup>8\u201310<\/jats:sup>\n and computer programming\n <jats:sup>11,12<\/jats:sup>\n . Here, we show the development and capabilities of Coscientist, an artificial intelligence system driven by GPT-4 that autonomously designs, plans and performs complex experiments by incorporating large language models empowered by tools such as internet and documentation search, code execution and experimental automation. Coscientist showcases its potential for accelerating research across six diverse tasks, including the successful reaction optimization of palladium-catalysed cross-couplings, while exhibiting advanced capabilities for (semi-)autonomous experimental design and execution. Our findings demonstrate the versatility, efficacy and explainability of artificial intelligence systems like Coscientist in advancing research.\n <\/jats:p>","DOI":"10.1038\/s41586-023-06792-0","type":"journal-article","created":{"date-parts":[[2023,12,20]],"date-time":"2023-12-20T12:02:31Z","timestamp":1703073751000},"page":"570-578","update-policy":"https:\/\/doi.org\/10.1007\/springer_crossmark_policy","source":"Crossref","is-referenced-by-count":1126,"title":["Autonomous chemical research with large language models"],"prefix":"10.1038","volume":"624","author":[{"ORCID":"https:\/\/orcid.org\/0000-0003-4140-4645","authenticated-orcid":false,"given":"Daniil A.","family":"Boiko","sequence":"first","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Robert","family":"MacKnight","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Ben","family":"Kline","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-8235-5969","authenticated-orcid":false,"given":"Gabe","family":"Gomes","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]}],"member":"297","published-online":{"date-parts":[[2023,12,20]]},"reference":[{"key":"6792_CR1","unstructured":"Brown, T. et al. in Advances in Neural Information Processing Systems Vol. 33 (eds Larochelle, H. et al.) 1877\u20131901 (Curran Associates, 2020)."},{"key":"6792_CR2","unstructured":"Thoppilan, R. et al. LaMDA: language models for dialog applications. Preprint at https:\/\/arxiv.org\/abs\/2201.08239 (2022)."},{"key":"6792_CR3","unstructured":"Touvron, H. et al. LLaMA: open and efficient foundation language models. Preprint at https:\/\/arxiv.org\/abs\/2302.13971 (2023)."},{"key":"6792_CR4","unstructured":"Hoffmann, J. et al. Training compute-optimal large language models. In Advances in Neural Information Processing Systems 30016\u201330030 (NeurIPS, 2022)."},{"key":"6792_CR5","unstructured":"Chowdhery, A. et al. PaLM: scaling language modeling with pathways. J. Mach. Learn. Res. 24, 1\u2013113 (2022)."},{"key":"6792_CR6","doi-asserted-by":"publisher","first-page":"1123","DOI":"10.1126\/science.ade2574","volume":"379","author":"Z Lin","year":"2023","unstructured":"Lin, Z. et al. Evolutionary-scale prediction of atomic-level protein structure with a language model. Science 379, 1123\u20131130 (2023).","journal-title":"Science"},{"key":"6792_CR7","doi-asserted-by":"publisher","first-page":"bbac409","DOI":"10.1093\/bib\/bbac409","volume":"23","author":"R Luo","year":"2022","unstructured":"Luo, R. et al. BioGPT: generative pre-trained transformer for biomedical text generation and mining. Brief Bioinform. 23, bbac409 (2022).","journal-title":"Brief Bioinform."},{"key":"6792_CR8","doi-asserted-by":"publisher","first-page":"015022","DOI":"10.1088\/2632-2153\/ac3ffb","volume":"3","author":"R Irwin","year":"2022","unstructured":"Irwin, R., Dimitriadis, S., He, J. & Bjerrum, E. J. Chemformer: a pre-trained transformer for computational chemistry. Mach. Learn. Sci. Technol. 3, 015022 (2022).","journal-title":"Mach. Learn. Sci. Technol."},{"key":"6792_CR9","doi-asserted-by":"publisher","first-page":"5804","DOI":"10.1021\/acs.jcim.1c01289","volume":"61","author":"H Kim","year":"2021","unstructured":"Kim, H., Na, J. & Lee, W. B. Generative chemical transformer: neural machine learning of molecular geometric structures from chemical language via attention. J. Chem. Inf. Model. 61, 5804\u20135814 (2021).","journal-title":"J. Chem. Inf. Model."},{"key":"6792_CR10","doi-asserted-by":"crossref","unstructured":"Jablonka, K. M., Schwaller, P., Ortega-Guerrero, A. & Smit, B. Leveraging large language models for predictive chemistry. Preprint at https:\/\/chemrxiv.org\/engage\/chemrxiv\/article-details\/652e50b98bab5d2055852dde (2023).","DOI":"10.26434\/chemrxiv-2023-fw8n4-v3"},{"key":"6792_CR11","doi-asserted-by":"crossref","unstructured":"Xu, F. F., Alon, U., Neubig, G. & Hellendoorn, V. J. A systematic evaluation of large language models of code. In Proc. 6th ACM SIGPLAN International Symposium on Machine Programming 1\u201310 (ACM, 2022).","DOI":"10.1145\/3520312.3534862"},{"key":"6792_CR12","unstructured":"Nijkamp, E. et al. CodeGen: an open large language model for code with multi-turn program synthesis. In Proc. 11th International Conference on Learning Representations (ICLR, 2022)."},{"key":"6792_CR13","unstructured":"Kaplan, J. et al. Scaling laws for neural language models. Preprint at https:\/\/arxiv.org\/abs\/2001.08361 (2020)."},{"key":"6792_CR14","unstructured":"OpenAI. GPT-4 Technical Report (OpenAI, 2023)."},{"key":"6792_CR15","unstructured":"Ziegler, D. M. et al. Fine-tuning language models from human preferences. Preprint at https:\/\/arxiv.org\/abs\/1909.08593 (2019)."},{"key":"6792_CR16","unstructured":"Ouyang, L. et al. Training language models to follow instructions with human feedback. In Advances in Neural Information Processing Systems 27730\u201327744 (NeurIPS, 2022)."},{"key":"6792_CR17","doi-asserted-by":"publisher","first-page":"377","DOI":"10.1038\/s41586-018-0307-8","volume":"559","author":"JM Granda","year":"2018","unstructured":"Granda, J. M., Donina, L., Dragone, V., Long, D.-L. & Cronin, L. Controlling an organic synthesis robot with machine learning to search for new reactivity. Nature 559, 377\u2013381 (2018).","journal-title":"Nature"},{"key":"6792_CR18","doi-asserted-by":"publisher","first-page":"1821","DOI":"10.1021\/acscentsci.1c00435","volume":"7","author":"D Caramelli","year":"2021","unstructured":"Caramelli, D. et al. Discovering new chemistry with an autonomous robotic platform driven by a reactivity-seeking neural network. ACS Cent. Sci. 7, 1821\u20131830 (2021).","journal-title":"ACS Cent. Sci."},{"key":"6792_CR19","doi-asserted-by":"publisher","first-page":"399","DOI":"10.1126\/science.adc8743","volume":"378","author":"NH Angello","year":"2022","unstructured":"Angello, N. H. et al. Closed-loop optimization of general reaction conditions for heteroaryl Suzuki\u2013Miyaura coupling. Science 378, 399\u2013405 (2022).","journal-title":"Science"},{"key":"6792_CR20","doi-asserted-by":"publisher","first-page":"61","DOI":"10.1126\/science.aaf1337","volume":"352","author":"A Adamo","year":"2016","unstructured":"Adamo, A. et al. On-demand continuous-flow production of pharmaceuticals in a compact, reconfigurable system. Science 352, 61\u201367 (2016).","journal-title":"Science"},{"key":"6792_CR21","doi-asserted-by":"publisher","first-page":"eaax1566","DOI":"10.1126\/science.aax1566","volume":"365","author":"CW Coley","year":"2019","unstructured":"Coley, C. W. et al. A robotic platform for flow synthesis of organic compounds informed by AI planning. Science 365, eaax1566 (2019).","journal-title":"Science"},{"key":"6792_CR22","doi-asserted-by":"publisher","first-page":"237","DOI":"10.1038\/s41586-020-2442-2","volume":"583","author":"B Burger","year":"2020","unstructured":"Burger, B. et al. A mobile robotic chemist. Nature 583, 237\u2013241 (2020).","journal-title":"Nature"},{"key":"6792_CR23","unstructured":"Auto-GPT: the heart of the open-source agent ecosystem. GitHub https:\/\/github.com\/Significant-Gravitas\/AutoGPT (2023)."},{"key":"6792_CR24","unstructured":"BabyAGI. GitHub https:\/\/github.com\/yoheinakajima\/babyagi (2023)."},{"key":"6792_CR25","unstructured":"Chase, H. LangChain. GitHub https:\/\/github.com\/langchain-ai\/langchain (2023)."},{"key":"6792_CR26","unstructured":"Bran, A. M., Cox, S., White, A. D. & Schwaller, P. ChemCrow: augmenting large-language models with chemistry tools. Preprint at https:\/\/arxiv.org\/abs\/2304.05376 (2023)."},{"key":"6792_CR27","doi-asserted-by":"crossref","unstructured":"Liu, P. et al. Pre-train, prompt, and predict: a systematic survey of prompting methods in natural language processing. ACM Comput. Surv. 55, 195 (2021).","DOI":"10.1145\/3560815"},{"key":"6792_CR28","unstructured":"Bai, Y. et al. Constitutional AI: harmlessness from AI feedback. Preprint at https:\/\/arxiv.org\/abs\/2212.08073 (2022)."},{"key":"6792_CR29","unstructured":"Falcon LLM. TII https:\/\/falconllm.tii.ae (2023)."},{"key":"6792_CR30","unstructured":"Open LLM Leaderboard. Hugging Face https:\/\/huggingface.co\/spaces\/HuggingFaceH4\/open_llm_leaderboard (2023)."},{"key":"6792_CR31","doi-asserted-by":"publisher","first-page":"248","DOI":"10.1145\/3571730","volume":"55","author":"Z Ji","year":"2023","unstructured":"Ji, Z. et al. Survey of hallucination in natural language generation. ACM Comput. Surv. 55, 248 (2023).","journal-title":"ACM Comput. Surv."},{"key":"6792_CR32","unstructured":"Reaxys https:\/\/www.reaxys.com (2023)."},{"key":"6792_CR33","unstructured":"SciFinder https:\/\/scifinder.cas.org (2023)."},{"key":"6792_CR34","unstructured":"Yao, S. et al. ReAct: synergizing reasoning and acting in language models. In Proc.11th International Conference on Learning Representations (ICLR, 2022)."},{"key":"6792_CR35","unstructured":"Wei, J. et al. Chain-of-thought prompting elicits reasoning in large language models. In Advances in Neural Information Processing Systems 24824\u201324837 (NeurIPS, 2022)."},{"key":"6792_CR36","unstructured":"Long, J. Large language model guided tree-of-thought. Preprint at https:\/\/arxiv.org\/abs\/2305.08291 (2023)."},{"key":"6792_CR37","unstructured":"Opentrons Python Protocol API. Opentrons https:\/\/docs.opentrons.com\/v2\/ (2023)."},{"key":"6792_CR38","doi-asserted-by":"crossref","unstructured":"Tu, Z. et al. Approximate nearest neighbor search and lightweight dense vector reranking in multi-stage retrieval architectures. In Proc. 2020 ACM SIGIR on International Conference on Theory of Information Retrieval 97\u2013100 (ACM, 2020).","DOI":"10.1145\/3409256.3409818"},{"key":"6792_CR39","doi-asserted-by":"crossref","unstructured":"Lin, J. et al. Pyserini: a python toolkit for reproducible information retrieval research with sparse and dense representations. In Proc. 44th International ACM SIGIR Conference on Research and Development in Information Retrieval 2356\u20132362 (ACM, 2021).","DOI":"10.1145\/3404835.3463238"},{"key":"6792_CR40","unstructured":"Qadrud-Din, J. et al. Transformer based language models for similar text retrieval and ranking. Preprint at https:\/\/arxiv.org\/abs\/2005.04588 (2020)."},{"key":"6792_CR41","unstructured":"Paper QA. GitHub https:\/\/github.com\/whitead\/paper-qa (2023)."},{"key":"6792_CR42","doi-asserted-by":"publisher","first-page":"333","DOI":"10.1561\/1500000019","volume":"3","author":"S Robertson","year":"2009","unstructured":"Robertson, S. & Zaragoza, H. The probabilistic relevance framework: BM25 and beyond. Found. Trends Inf. Retrieval 3, 333\u2013389 (2009).","journal-title":"Found. Trends Inf. Retrieval"},{"key":"6792_CR43","unstructured":"Data Mining. Mining of Massive Datasets (Cambridge Univ., 2011)."},{"key":"6792_CR44","doi-asserted-by":"publisher","first-page":"535","DOI":"10.1109\/TBDATA.2019.2921572","volume":"7","author":"J Johnson","year":"2021","unstructured":"Johnson, J., Douze, M. & Jegou, H. Billion-scale similarity search with GPUs. IEEE Trans. Big Data 7, 535\u2013547 (2021).","journal-title":"IEEE Trans. Big Data"},{"key":"6792_CR45","doi-asserted-by":"publisher","first-page":"324","DOI":"10.1177\/0165551506065787","volume":"32","author":"O Vechtomova","year":"2006","unstructured":"Vechtomova, O. & Wang, Y. A study of the effect of term proximity on query expansion. J. Inf. Sci. 32, 324\u2013333 (2006).","journal-title":"J. Inf. Sci."},{"key":"6792_CR46","unstructured":"Running experiments. Emerald Cloud Lab https:\/\/www.emeraldcloudlab.com\/guides\/runningexperiments (2023)."},{"key":"6792_CR47","doi-asserted-by":"publisher","first-page":"103","DOI":"10.1039\/D2DD00071G","volume":"2","author":"R Sanchez-Garcia","year":"2023","unstructured":"Sanchez-Garcia, R. et al. CoPriNet: graph neural networks provide accurate and rapid compound price prediction for molecule prioritisation. Digital Discov. 2, 103\u2013111 (2023).","journal-title":"Digital Discov."},{"key":"6792_CR48","unstructured":"Bubeck, S. et al. Sparks of artificial general intelligence: early experiments with GPT-4. Preprint at https:\/\/arxiv.org\/abs\/2303.12712 (2023)."},{"key":"6792_CR49","unstructured":"Ramos, M. C., Michtavy, S. S., Porosoff, M. D. & White, A. D. Bayesian optimization of catalysts with in-context learning. Preprint at https:\/\/arxiv.org\/abs\/2304.05341 (2023)."},{"key":"6792_CR50","doi-asserted-by":"publisher","first-page":"429","DOI":"10.1126\/science.aap9112","volume":"359","author":"D Perera","year":"2018","unstructured":"Perera, D. et al. A platform for automated nanomole-scale reaction screening and micromole-scale synthesis in flow. Science 359, 429\u2013434 (2018).","journal-title":"Science"},{"key":"6792_CR51","doi-asserted-by":"publisher","first-page":"186","DOI":"10.1126\/science.aar5169","volume":"360","author":"DT Ahneman","year":"2018","unstructured":"Ahneman, D. T., Estrada, J. G., Lin, S., Dreher, S. D. & Doyle, A. G. Predicting reaction performance in C\u2013N cross-coupling using machine learning. Science 360, 186\u2013190 (2018).","journal-title":"Science"},{"key":"6792_CR52","doi-asserted-by":"crossref","unstructured":"Hickman, R. et al. Atlas: a brain for self-driving laboratories. Preprint at https:\/\/chemrxiv.org\/engage\/chemrxiv\/article-details\/64f6560579853bbd781bcef6 (2023).","DOI":"10.26434\/chemrxiv-2023-8nrxx"}],"container-title":["Nature"],"original-title":[],"language":"en","link":[{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06792-0.pdf","content-type":"application\/pdf","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06792-0","content-type":"text\/html","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06792-0.pdf","content-type":"application\/pdf","content-version":"vor","intended-application":"similarity-checking"}],"deposited":{"date-parts":[[2023,12,21]],"date-time":"2023-12-21T02:11:29Z","timestamp":1703124689000},"score":1,"resource":{"primary":{"URL":"https:\/\/www.nature.com\/articles\/s41586-023-06792-0"}},"subtitle":[],"short-title":[],"issued":{"date-parts":[[2023,12,20]]},"references-count":52,"journal-issue":{"issue":"7992","published-print":{"date-parts":[[2023,12,21]]}},"alternative-id":["6792"],"URL":"https:\/\/doi.org\/10.1038\/s41586-023-06792-0","relation":{},"ISSN":["0028-0836","1476-4687"],"issn-type":[{"value":"0028-0836","type":"print"},{"value":"1476-4687","type":"electronic"}],"subject":[],"published":{"date-parts":[[2023,12,20]]},"assertion":[{"value":"20 April 2023","order":1,"name":"received","label":"Received","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"27 October 2023","order":2,"name":"accepted","label":"Accepted","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"20 December 2023","order":3,"name":"first_online","label":"First Online","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"G.G. is part of the AI Scientific Advisory Board of Emerald Cloud Lab. Experiments and conclusions in this manuscript were made before G.G.\u2019s appointment to this role. B.K. is an employee of Emerald Cloud Lab. D.A.B. and G.G. are co-founders of aithera.ai, a company focusing on responsible use of artificial intelligence for research.","order":1,"name":"Ethics","group":{"name":"EthicsHeading","label":"Competing interests"}}]}} | ||||
| \ No newline at end of file | |||||
added
research/verify_cache/https_api_crossref_org_works_10_1038_2Fs41586_025_09442_9
+1 −0
@@ -0,0 +1 @@ | |||||
| 1 | +{"status":"ok","message-type":"work","message-version":"1.0.0","message":{"indexed":{"date-parts":[[2026,10,29]],"date-time":"2026-10-29T15:59:13Z","timestamp":1793289553263,"version":"4.5.0"},"reference-count":63,"publisher":"Springer Science and Business Media LLC","issue":"8085","license":[{"start":{"date-parts":[[2025,7,29]],"date-time":"2025-07-29T00:00:00Z","timestamp":1753747200000},"content-version":"tdm","delay-in-days":0,"URL":"https:\/\/www.springernature.com\/gp\/researchers\/text-and-data-mining"},{"start":{"date-parts":[[2025,7,29]],"date-time":"2025-07-29T00:00:00Z","timestamp":1753747200000},"content-version":"vor","delay-in-days":0,"URL":"https:\/\/www.springernature.com\/gp\/researchers\/text-and-data-mining"}],"content-domain":{"domain":["link.springer.com"],"crossmark-restriction":false},"short-container-title":["Nature"],"published-print":{"date-parts":[[2025,10,16]]},"DOI":"10.1038\/s41586-025-09442-9","type":"journal-article","created":{"date-parts":[[2025,7,29]],"date-time":"2025-07-29T15:02:35Z","timestamp":1753801355000},"page":"716-723","update-policy":"https:\/\/doi.org\/10.1007\/springer_crossmark_policy","source":"Crossref","is-referenced-by-count":198,"title":["The Virtual Lab of AI agents designs new SARS-CoV-2 nanobodies"],"prefix":"10.1038","volume":"646","author":[{"ORCID":"https:\/\/orcid.org\/0000-0002-7385-7844","authenticated-orcid":false,"given":"Kyle","family":"Swanson","sequence":"first","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0003-4594-0699","authenticated-orcid":false,"given":"Wesley","family":"Wu","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"given":"Nash L.","family":"Bulaong","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0002-2998-9735","authenticated-orcid":false,"given":"John E.","family":"Pak","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]},{"ORCID":"https:\/\/orcid.org\/0000-0001-8880-4764","authenticated-orcid":false,"given":"James","family":"Zou","sequence":"additional","affiliation":[],"role":[{"vocabulary":"crossref","role":"author"}]}],"member":"297","published-online":{"date-parts":[[2025,7,29]]},"reference":[{"key":"9442_CR1","doi-asserted-by":"publisher","first-page":"719","DOI":"10.1007\/s11192-008-2197-2","volume":"81","author":"AL Porter","year":"2009","unstructured":"Porter, A. L. & Rafols, I. Is science becoming more interdisciplinary? Measuring and mapping six research fields over time. Scientometrics 81, 719\u2013745 (2009).","journal-title":"Scientometrics"},{"key":"9442_CR2","unstructured":"Sijp, W. Paper authorship goes hyper. Nature Index www.nature.com\/nature-index\/news\/paper-authorship-goes-hyper (2018)."},{"key":"9442_CR3","doi-asserted-by":"publisher","unstructured":"Castelvecchi, D. Physics paper sets record with more than 5,000 authors. Nature https:\/\/doi.org\/10.1038\/nature.2015.17567 (2015).","DOI":"10.1038\/nature.2015.17567"},{"key":"9442_CR4","doi-asserted-by":"publisher","first-page":"e0278043","DOI":"10.1371\/journal.pone.0278043","volume":"17","author":"A Specht","year":"2022","unstructured":"Specht, A. & Crowston, K. Interdisciplinary collaboration from diverse science teams can produce significant outcomes. PLoS ONE 17, e0278043 (2022).","journal-title":"PLoS ONE"},{"key":"9442_CR5","doi-asserted-by":"publisher","first-page":"101966","DOI":"10.1016\/j.erss.2021.101966","volume":"74","author":"JJ Cohen","year":"2021","unstructured":"Cohen, J. J. et al. Tackling the challenge of interdisciplinary energy research: a research toolkit. Energy Res. Soc. Sci. 74, 101966 (2021).","journal-title":"Energy Res. Soc. Sci."},{"key":"9442_CR6","doi-asserted-by":"publisher","first-page":"e0000198","DOI":"10.1371\/journal.pdig.0000198","volume":"2","author":"TH Kung","year":"2023","unstructured":"Kung, T. H. et al. Performance of ChatGPT on USMLE: potential for AI-assisted medical education using large language models. PLOS Digit. Health 2, e0000198 (2023).","journal-title":"PLOS Digit. Health"},{"key":"9442_CR7","doi-asserted-by":"publisher","first-page":"172","DOI":"10.1038\/s41586-023-06291-2","volume":"620","author":"K Singhal","year":"2023","unstructured":"Singhal, K. et al. Large language models encode clinical knowledge. Nature 620, 172\u2013180 (2023).","journal-title":"Nature"},{"key":"9442_CR8","doi-asserted-by":"publisher","unstructured":"Laurent, J. M. et al. LAB-Bench: measuring capabilities of language models for biology research. Preprint at https:\/\/doi.org\/10.48550\/arXiv.2407.10362 (2024).","DOI":"10.48550\/arXiv.2407.10362"},{"key":"9442_CR9","first-page":"59662","volume":"36","author":"T Guo","year":"2023","unstructured":"Guo, T. et al. What can large language models do in chemistry? A comprehensive benchmark on eight tasks. Adv. Neural Inf. Process. Syst. 36, 59662\u201359688 (2023).","journal-title":"Adv. Neural Inf. Process. Syst."},{"key":"9442_CR10","first-page":"19053","volume":"38","author":"L Sun","year":"2024","unstructured":"Sun, L. et al. SciEval: a multi-level large language model evaluation benchmark for scientific research. Proc. AAAI Conf. Artif. Intell. 38, 19053\u201319061 (2024).","journal-title":"Proc. AAAI Conf. Artif. Intell."},{"key":"9442_CR11","doi-asserted-by":"publisher","DOI":"10.1038\/s41598-024-55568-7","volume":"14","author":"D Stribling","year":"2024","unstructured":"Stribling, D. et al. The model student: GPT-4 performance on graduate biomedical science exams. Sci. Rep. 14, 5670 (2024).","journal-title":"Sci. Rep."},{"key":"9442_CR12","doi-asserted-by":"publisher","DOI":"10.1016\/S1473-3099(23)00813-7","volume":"24","author":"Y Kaku","year":"2024","unstructured":"Kaku, Y. et al. Virological characteristics of the SARS-CoV-2 JN.1 variant. Lancet Infect. Dis. 24, e82 (2024).","journal-title":"Lancet Infect. Dis."},{"key":"9442_CR13","doi-asserted-by":"publisher","first-page":"e482","DOI":"10.1016\/S1473-3099(24)00415-8","volume":"24","author":"Y Kaku","year":"2024","unstructured":"Kaku, Y. et al. Virological characteristics of the SARS-CoV-2 KP.3, LB.1, and KP.2.3 variants. Lancet Infect. Dis. 24, e482\u2013e483 (2024).","journal-title":"Lancet Infect. Dis."},{"key":"9442_CR14","doi-asserted-by":"publisher","first-page":"583","DOI":"10.1038\/s41586-021-03819-2","volume":"596","author":"J Jumper","year":"2021","unstructured":"Jumper, J. et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583\u2013589 (2021).","journal-title":"Nature"},{"key":"9442_CR15","doi-asserted-by":"publisher","first-page":"525","DOI":"10.1038\/d41586-024-03214-7","volume":"634","author":"E Callaway","year":"2024","unstructured":"Callaway, E. Chemistry Nobel goes to developers of AlphaFold AI that predicts protein structures. Nature 634, 525\u2013526 (2024).","journal-title":"Nature"},{"key":"9442_CR16","doi-asserted-by":"publisher","first-page":"684","DOI":"10.1038\/nature18315","volume":"534","author":"L Bromham","year":"2016","unstructured":"Bromham, L., Dinnage, R. & Hua, X. Interdisciplinary research has consistently lower funding success. Nature 534, 684\u2013687 (2016).","journal-title":"Nature"},{"key":"9442_CR17","doi-asserted-by":"publisher","unstructured":"OpenAI et al. GPT-4 Technical Report. Preprint at https:\/\/doi.org\/10.48550\/arXiv.2303.08774 (2024).","DOI":"10.48550\/arXiv.2303.08774"},{"key":"9442_CR18","unstructured":"Anthropic. The Claude 3 Model Family: Opus, Sonnet, Haiku (Anthropic, 2024)."},{"key":"9442_CR19","doi-asserted-by":"publisher","first-page":"1422","DOI":"10.1038\/s41592-024-02354-y","volume":"21","author":"E Simon","year":"2024","unstructured":"Simon, E., Swanson, K. & Zou, J. Language models for biological research: a primer. Nat. Methods 21, 1422\u20131429 (2024).","journal-title":"Nat. Methods"},{"key":"9442_CR20","doi-asserted-by":"publisher","first-page":"525","DOI":"10.1038\/s42256-024-00832-8","volume":"6","author":"A M. Bran","year":"2024","unstructured":"M. Bran, A. et al. Augmenting large language models with chemistry tools. Nat. Mach. Intell. 6, 525\u2013535 (2024).","journal-title":"Nat. Mach. Intell."},{"key":"9442_CR21","doi-asserted-by":"publisher","first-page":"570","DOI":"10.1038\/s41586-023-06792-0","volume":"624","author":"DA Boiko","year":"2023","unstructured":"Boiko, D. A., MacKnight, R., Kline, B. & Gomes, G. Autonomous chemical research with large language models. Nature 624, 570\u2013578 (2023).","journal-title":"Nature"},{"key":"9442_CR22","doi-asserted-by":"publisher","unstructured":"Lu, C. et al. The AI scientist: towards fully automated open-ended scientific discovery. Preprint at https:\/\/doi.org\/10.48550\/arXiv.2408.06292 (2024).","DOI":"10.48550\/arXiv.2408.06292"},{"key":"9442_CR23","unstructured":"Si, C., Yang, D. & Hashimoto, T. Can LLMs generate novel research ideas? A large-scale human study with 100+ NLP researchers. in 13th Int. Conf. Learn. Represent. https:\/\/openreview.net\/pdf?id=M23dTGWCZy (ICLR, 2025)."},{"key":"9442_CR24","unstructured":"Wu, Q. et al. AutoGen: enabling next-gen LLM applications via multi-agent conversation. In 1st Conf. Lang. Model. https:\/\/openreview.net\/forum?id=BAakY1hNKS (COLM, 2024)."},{"key":"9442_CR25","doi-asserted-by":"publisher","first-page":"6125","DOI":"10.1016\/j.cell.2024.09.022","volume":"187","author":"S Gao","year":"2024","unstructured":"Gao, S. et al. Empowering biomedical discovery with AI agents. Cell 187, 6125\u20136151 (2024).","journal-title":"Cell"},{"key":"9442_CR26","doi-asserted-by":"publisher","first-page":"1123","DOI":"10.1126\/science.ade2574","volume":"379","author":"Z Lin","year":"2023","unstructured":"Lin, Z. et al. Evolutionary-scale prediction of atomic-level protein structure with a language model. Science 379, 1123\u20131130 (2023).","journal-title":"Science"},{"key":"9442_CR27","doi-asserted-by":"publisher","unstructured":"Evans, R. et al. Protein complex prediction with AlphaFold-Multimer. Preprint at https:\/\/doi.org\/10.1101\/2021.10.04.463034 (2021).","DOI":"10.1101\/2021.10.04.463034"},{"key":"9442_CR28","doi-asserted-by":"publisher","first-page":"196","DOI":"10.1002\/prot.26422","volume":"91","author":"VS Boorla","year":"2023","unstructured":"Boorla, V. S. et al. De novo design and Rosetta\u2010based assessment of high\u2010affinity antibody variable regions (Fv) against the SARS\u2010CoV \u20102 spike receptor binding domain (RBD). Proteins Struct. Funct. Bioinformatics 91, 196\u2013208 (2023).","journal-title":"Proteins Struct. Funct. Bioinformatics"},{"key":"9442_CR29","doi-asserted-by":"publisher","unstructured":"OpenAI et al. GPT-4o System Card. Preprint at https:\/\/doi.org\/10.48550\/arXiv.2410.21276 (2024).","DOI":"10.48550\/arXiv.2410.21276"},{"key":"9442_CR30","doi-asserted-by":"publisher","first-page":"657","DOI":"10.1038\/s41586-021-04385-3","volume":"602","author":"Y Cao","year":"2022","unstructured":"Cao, Y. et al. Omicron escapes the majority of existing SARS-CoV-2 neutralizing antibodies. Nature 602, 657\u2013663 (2022).","journal-title":"Nature"},{"key":"9442_CR31","doi-asserted-by":"publisher","first-page":"671","DOI":"10.1038\/s41586-021-04389-z","volume":"602","author":"D Planas","year":"2022","unstructured":"Planas, D. et al. Considerable escape of SARS-CoV-2 Omicron to antibody neutralization. Nature 602, 671\u2013675 (2022).","journal-title":"Nature"},{"key":"9442_CR32","doi-asserted-by":"publisher","DOI":"10.1038\/s41467-020-18174-5","volume":"11","author":"L Hanke","year":"2020","unstructured":"Hanke, L. et al. An alpaca nanobody neutralizes SARS-CoV-2 by blocking receptor interaction. Nat. Commun. 11, 4420 (2020).","journal-title":"Nat. Commun."},{"key":"9442_CR33","doi-asserted-by":"publisher","first-page":"846","DOI":"10.1038\/s41594-020-0469-6","volume":"27","author":"J Huo","year":"2020","unstructured":"Huo, J. et al. Neutralizing nanobodies bind SARS-CoV-2 spike RBD and block interaction with ACE2. Nat. Struct. Mol. Biol. 27, 846\u2013854 (2020).","journal-title":"Nat. Struct. Mol. Biol."},{"key":"9442_CR34","doi-asserted-by":"publisher","first-page":"1479","DOI":"10.1126\/science.abe4747","volume":"370","author":"Y Xiang","year":"2020","unstructured":"Xiang, Y. et al. Versatile and multivalent nanobodies efficiently neutralize SARS-CoV-2. Science 370, 1479\u20131484 (2020).","journal-title":"Science"},{"key":"9442_CR35","doi-asserted-by":"publisher","first-page":"1004","DOI":"10.1016\/j.cell.2020.04.031","volume":"181","author":"D Wrapp","year":"2020","unstructured":"Wrapp, D. et al. Structural basis for potent neutralization of betacoronaviruses by single-domain camelid antibodies. Cell 181, 1004\u20131015.e15 (2020).","journal-title":"Cell"},{"key":"9442_CR36","doi-asserted-by":"publisher","first-page":"e4865","DOI":"10.1002\/pro.4865","volume":"33","author":"R Yin","year":"2024","unstructured":"Yin, R. & Pierce, B. G. Evaluation of AlphaFold antibody\u2013antigen modeling with implications for improving predictive accuracy. Protein Sci. 33, e4865 (2024).","journal-title":"Protein Sci."},{"key":"9442_CR37","doi-asserted-by":"publisher","first-page":"1","DOI":"10.1111\/cbdd.13847","volume":"98","author":"J Yang","year":"2021","unstructured":"Yang, J. et al. Computational design and modeling of nanobodies toward SARS\u2010CoV\u20102 receptor binding domain. Chem. Biol. Drug Des. 98, 1\u201318 (2021).","journal-title":"Chem. Biol. Drug Des."},{"key":"9442_CR38","doi-asserted-by":"publisher","first-page":"275","DOI":"10.1038\/s41587-023-01763-2","volume":"42","author":"BL Hie","year":"2024","unstructured":"Hie, B. L. et al. Efficient evolution of human antibodies from general protein language models. Nat. Biotechnol. 42, 275\u2013283 (2024).","journal-title":"Nat. Biotechnol."},{"key":"9442_CR39","doi-asserted-by":"publisher","first-page":"1","DOI":"10.20411\/pai.v10i1.752","volume":"10","author":"D Planas","year":"2024","unstructured":"Planas, D. et al. Escape of SARS-CoV-2 variants KP.1.1, LB.1, and KP3.3 from approved monoclonal antibodies. Pathog. Immun. 10, 1 (2024).","journal-title":"Pathog. Immun."},{"key":"9442_CR40","unstructured":"Chan, C.-M. et al. ChatEval: towards better LLM-based evaluators through multi-agent debate. In 12th Int. Conf. Learn. Represent. https:\/\/openreview.net\/forum?id=FQepisCUWu (ICLR, 2024)."},{"key":"9442_CR41","unstructured":"Liu, Z., Zhang, Y., Li, P., Liu, Y. & Yang, D. A dynamic LLM-powered agent network for task-oriented agent collaboration. In 1st Conf. on Lang. Model. https:\/\/openreview.net\/forum?id=XII0Wp1XA9 (COLM, 2024)."},{"key":"9442_CR42","doi-asserted-by":"publisher","unstructured":"Talebirad, Y. & Nadiri, A. Multi-agent collaboration: harnessing the power of intelligent LLM agents. Preprint at https:\/\/doi.org\/10.48550\/arXiv.2306.03314 (2023).","DOI":"10.48550\/arXiv.2306.03314"},{"key":"9442_CR43","unstructured":"Wei, J. et al. Chain-of-thought prompting elicits reasoning in large language models. In Proc. 36th International Conference on Neural Information Processing Systems 24824\u201324837 (Curran Associates, 2024)."},{"key":"9442_CR44","unstructured":"Cheng, J. et al. Dated data: tracing knowledge cutoffs in large language models. In 1st Conf. Lang. Model. https:\/\/openreview.net\/forum?id=wS7PxDjy6m (COLM, 2024)."},{"key":"9442_CR45","doi-asserted-by":"publisher","first-page":"493","DOI":"10.1038\/s41586-024-07487-w","volume":"630","author":"J Abramson","year":"2024","unstructured":"Abramson, J. et al. Accurate structure prediction of biomolecular interactions with AlphaFold 3. Nature 630, 493\u2013500 (2024).","journal-title":"Nature"},{"key":"9442_CR46","first-page":"9459","volume":"33","author":"P Lewis","year":"2020","unstructured":"Lewis, P. et al. Retrieval-augmented generation for knowledge-intensive NLP tasks. Adv. Neural Inf. Process. Syst. 33, 9459\u20139474 (2020).","journal-title":"Adv. Neural Inf. Process. Syst."},{"key":"9442_CR47","doi-asserted-by":"publisher","unstructured":"Gao, Y. et al. Retrieval-augmented generation for large language models: a survey. Preprint at https:\/\/doi.org\/10.48550\/arXiv.2312.10997 (2024).","DOI":"10.48550\/arXiv.2312.10997"},{"key":"9442_CR48","doi-asserted-by":"publisher","first-page":"220","DOI":"10.1038\/s42256-023-00626-4","volume":"5","author":"N Ding","year":"2023","unstructured":"Ding, N. et al. Parameter-efficient fine-tuning of large-scale pre-trained language models. Nat. Mach. Intell. 5, 220\u2013235 (2023).","journal-title":"Nat. Mach. Intell."},{"key":"9442_CR49","unstructured":"White, J. et al. A prompt pattern catalog to enhance prompt engineering with ChatGPT. In Proc. 30th Conference on Pattern Languages of Programs 1\u201331 (Hillside Group, 2023)."},{"key":"9442_CR50","doi-asserted-by":"publisher","first-page":"1","DOI":"10.1145\/3571730","volume":"55","author":"Z Ji","year":"2023","unstructured":"Ji, Z. et al. Survey of hallucination in natural language generation. ACM Comput. Surv. 55, 1\u201338 (2023).","journal-title":"ACM Comput. Surv."},{"key":"9442_CR51","doi-asserted-by":"publisher","DOI":"10.1002\/pro.4792","volume":"32","author":"EC Meng","year":"2023","unstructured":"Meng, E. C. et al. UCSF ChimeraX: tools for structure building and analysis. Protein Sci. 32, e4792 (2023).","journal-title":"Protein Sci."},{"key":"9442_CR52","doi-asserted-by":"publisher","first-page":"609","DOI":"10.1038\/s41586-025-08661-4","volume":"639","author":"M Yuksekgonul","year":"2025","unstructured":"Yuksekgonul, M. et al. Optimizing generative AI by backpropagating language model feedback. Nature 639, 609\u2013616 (2025).","journal-title":"Nature"},{"key":"9442_CR53","unstructured":"Peeperkorn, M., Kouwenhoven, T., Brown, D. & Jordanous, A. Is temperature the creativity parameter of large language models? In 15th Int. Conf. Comput. Creativity (Association for Computational Creativity, 2024)."},{"key":"9442_CR54","doi-asserted-by":"crossref","unstructured":"Chen, H. & Ding, N. Probing the \u201ccreativity\u201d of large language models: can models produce divergent semantic association? In Findings of the Association for Computational Linguistics: EMNLP 2023 (eds Bouamor, H., Pino, J. & Bali, K.) 12881\u201312888 (Association for Computational Linguistics, 2023).","DOI":"10.18653\/v1\/2023.findings-emnlp.858"},{"key":"9442_CR55","unstructured":"Chen, L. et al. Are more LLM calls all you need? Towards the scaling properties of compound AI systems. In 38th Annual Conference on Neural Information Processing Systems (NeurIPS, 2024)."},{"key":"9442_CR56","doi-asserted-by":"publisher","first-page":"679","DOI":"10.1038\/s41592-022-01488-1","volume":"19","author":"M Mirdita","year":"2022","unstructured":"Mirdita, M. et al. ColabFold: making protein folding accessible to all. Nat. Methods 19, 679\u2013682 (2022).","journal-title":"Nat. Methods"},{"key":"9442_CR57","doi-asserted-by":"publisher","first-page":"4780","DOI":"10.1002\/jmv.27927","volume":"94","author":"S Kumar","year":"2022","unstructured":"Kumar, S., Karuppanan, K. & Subramaniam, G. Omicron (BA.1) and sub-variants (BA.1.1, BA.2, and BA.3) of SARS-CoV-2 spike infectivity and pathogenicity: A comparative sequence and structural-based computational assessment. J. Med. Virol. 94, 4780\u20134791 (2022).","journal-title":"J. Med. Virol."},{"key":"9442_CR58","doi-asserted-by":"publisher","first-page":"e0297879","DOI":"10.1371\/journal.pone.0297879","volume":"19","author":"RR Puccinelli","year":"2024","unstructured":"Puccinelli, R. R. et al. Open-source milligram-scale, four channel, automated protein purification system. PLoS ONE 19, e0297879 (2024).","journal-title":"PLoS ONE"},{"key":"9442_CR59","doi-asserted-by":"crossref","unstructured":"Saez, N. J. & Vincentelli, R. in Structural Genomics: General Applications (ed. Chen, Y. W.) 33\u201353 (Humana Press, 2014).","DOI":"10.1007\/978-1-62703-691-7_3"},{"key":"9442_CR60","doi-asserted-by":"publisher","first-page":"674","DOI":"10.1038\/nprot.2014.039","volume":"9","author":"E Pardon","year":"2014","unstructured":"Pardon, E. et al. A general protocol for the generation of Nanobodies for structural biology. Nat. Protoc. 9, 674\u2013693 (2014).","journal-title":"Nat. Protoc."},{"key":"9442_CR61","doi-asserted-by":"publisher","first-page":"671","DOI":"10.3390\/pathogens12050671","volume":"12","author":"JR Byrum","year":"2023","unstructured":"Byrum, J. R. et al. MultiSero: an open-source multiplex-ELISA platform for measuring antibody responses to infection. Pathogens 12, 671 (2023).","journal-title":"Pathogens"},{"key":"9442_CR62","doi-asserted-by":"publisher","unstructured":"Swanson, K., Wu, W., Bulaong, N., Pak, J. & Zou, J. Virtual Lab Data. Zenodo https:\/\/doi.org\/10.5281\/zenodo.15331309 (2025).","DOI":"10.5281\/zenodo.15331309"},{"key":"9442_CR63","doi-asserted-by":"publisher","unstructured":"Swanson, K. Virtual Lab Code. Zenodo https:\/\/doi.org\/10.5281\/zenodo.15320492 (2025).","DOI":"10.5281\/zenodo.15320492"}],"container-title":["Nature"],"original-title":[],"language":"en","link":[{"URL":"https:\/\/www.nature.com\/articles\/s41586-025-09442-9.pdf","content-type":"application\/pdf","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/www.nature.com\/articles\/s41586-025-09442-9","content-type":"text\/html","content-version":"vor","intended-application":"text-mining"},{"URL":"https:\/\/www.nature.com\/articles\/s41586-025-09442-9.pdf","content-type":"application\/pdf","content-version":"vor","intended-application":"similarity-checking"}],"deposited":{"date-parts":[[2025,10,15]],"date-time":"2025-10-15T15:55:28Z","timestamp":1760543728000},"score":1,"resource":{"primary":{"URL":"https:\/\/www.nature.com\/articles\/s41586-025-09442-9"}},"subtitle":[],"short-title":[],"issued":{"date-parts":[[2025,7,29]]},"references-count":63,"journal-issue":{"issue":"8085","published-print":{"date-parts":[[2025,10,16]]}},"alternative-id":["9442"],"URL":"https:\/\/doi.org\/10.1038\/s41586-025-09442-9","relation":{},"ISSN":["0028-0836","1476-4687"],"issn-type":[{"value":"0028-0836","type":"print"},{"value":"1476-4687","type":"electronic"}],"subject":[],"published":{"date-parts":[[2025,7,29]]},"assertion":[{"value":"26 November 2024","order":1,"name":"received","label":"Received","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"22 July 2025","order":2,"name":"accepted","label":"Accepted","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"29 July 2025","order":3,"name":"first_online","label":"First Online","group":{"name":"ArticleHistory","label":"Article History"}},{"value":"The authors declare no competing interests.","order":1,"name":"Ethics","group":{"name":"EthicsHeading","label":"Competing interests"}}]}} | ||||
| \ No newline at end of file | |||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2211_11501
+52 −0
@@ -0,0 +1,52 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/2pQrt/Js9HlITvfRfK0KcoHyUMs</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2211.11501&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:08Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2211.11501" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2211.11501v1</id> | ||||
| 12 | + <title>DS-1000: A Natural and Reliable Benchmark for Data Science Code Generation</title> | ||||
| 13 | + <updated>2022-11-18T17:20:27Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2211.11501v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2211.11501v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>We introduce DS-1000, a code generation benchmark with a thousand data science problems spanning seven Python libraries, such as NumPy and Pandas. Compared to prior works, DS-1000 incorporates three core features. First, our problems reflect diverse, realistic, and practical use cases since we collected them from StackOverflow. Second, our automatic evaluation is highly specific (reliable) -- across all Codex-002-predicted solutions that our evaluation accept, only 1.8% of them are incorrect; we achieve this with multi-criteria metrics, checking both functional correctness by running test cases and surface-form constraints by restricting API usages or keywords. Finally, we proactively defend against memorization by slightly modifying our problems to be different from the original StackOverflow source; consequently, models cannot answer them correctly by memorizing the solutions from pre-training. The current best public system (Codex-002) achieves 43.3% accuracy, leaving ample room for improvement. We release our benchmark at https://ds1000-code-gen.github.io.</summary> | ||||
| 17 | + <category term="cs.SE" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2022-11-18T17:20:27Z</published> | ||||
| 20 | + <arxiv:primary_category term="cs.SE"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Yuhang Lai</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Chengxi Li</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Yiming Wang</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Tianyi Zhang</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Ruiqi Zhong</name> | ||||
| 35 | + </author> | ||||
| 36 | + <author> | ||||
| 37 | + <name>Luke Zettlemoyer</name> | ||||
| 38 | + </author> | ||||
| 39 | + <author> | ||||
| 40 | + <name>Scott Wen-tau Yih</name> | ||||
| 41 | + </author> | ||||
| 42 | + <author> | ||||
| 43 | + <name>Daniel Fried</name> | ||||
| 44 | + </author> | ||||
| 45 | + <author> | ||||
| 46 | + <name>Sida Wang</name> | ||||
| 47 | + </author> | ||||
| 48 | + <author> | ||||
| 49 | + <name>Tao Yu</name> | ||||
| 50 | + </author> | ||||
| 51 | + </entry> | ||||
| 52 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2305_02251
+41 −0
@@ -0,0 +1,41 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/1n/8exWCzn9tl3rNb+oJrO0StEY</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2305.02251&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:01Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2305.02251" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2305.02251v2</id> | ||||
| 12 | + <title>Automated Scientific Discovery: From Equation Discovery to Autonomous Discovery Systems</title> | ||||
| 13 | + <updated>2025-05-26T08:59:45Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2305.02251v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2305.02251v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>The paper surveys automated scientific discovery, from equation discovery and symbolic regression to autonomous discovery systems and agents. It discusses the individual approaches from a "big picture" perspective and in context, but also discusses open issues and recent topics like the various roles of deep neural networks in this area, aiding in the discovery of human-interpretable knowledge. Further, we will present closed-loop scientific discovery systems, starting with the pioneering work on the Adam system up to current efforts in fields from material science to astronomy. Finally, we will elaborate on autonomy from a machine learning perspective, but also in analogy to the autonomy levels in autonomous driving. The maximal level, level five, is defined to require no human intervention at all in the production of scientific knowledge. Achieving this is one step towards solving the Nobel Turing Grand Challenge to develop AI Scientists: AI systems capable of making Nobel-quality scientific discoveries highly autonomously at a level comparable, and possibly superior, to the best human scientists by 2050.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2023-05-03T16:35:41Z</published> | ||||
| 20 | + <arxiv:comment>19 pages plus references</arxiv:comment> | ||||
| 21 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 22 | + <arxiv:journal_ref>Machine Learning (2026) 115:109</arxiv:journal_ref> | ||||
| 23 | + <author> | ||||
| 24 | + <name>Stefan Kramer</name> | ||||
| 25 | + </author> | ||||
| 26 | + <author> | ||||
| 27 | + <name>Mattia Cerrato</name> | ||||
| 28 | + </author> | ||||
| 29 | + <author> | ||||
| 30 | + <name>Jannis Brugger</name> | ||||
| 31 | + </author> | ||||
| 32 | + <author> | ||||
| 33 | + <name>Sašo Džeroski</name> | ||||
| 34 | + </author> | ||||
| 35 | + <author> | ||||
| 36 | + <name>Ross King</name> | ||||
| 37 | + </author> | ||||
| 38 | + <arxiv:doi>10.1007/s10994-025-06955-2</arxiv:doi> | ||||
| 39 | + <link rel="related" href="https://doi.org/10.1007/s10994-025-06955-2" title="doi"/> | ||||
| 40 | + </entry> | ||||
| 41 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2310_03302
+34 −0
@@ -0,0 +1,34 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/UcHtoazeYL9/aJEnHE81yJHExQ8</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2310.03302&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:02Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2310.03302" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2310.03302v2</id> | ||||
| 12 | + <title>MLAgentBench: Evaluating Language Agents on Machine Learning Experimentation</title> | ||||
| 13 | + <updated>2024-04-14T21:02:16Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2310.03302v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2310.03302v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>A central aspect of machine learning research is experimentation, the process of designing and running experiments, analyzing the results, and iterating towards some positive outcome (e.g., improving accuracy). Could agents driven by powerful language models perform machine learning experimentation effectively? To answer this question, we introduce MLAgentBench, a suite of 13 tasks ranging from improving model performance on CIFAR-10 to recent research problems like BabyLM. For each task, an agent can perform actions like reading/writing files, executing code, and inspecting outputs. We then construct an agent that can perform ML experimentation based on ReAct framework. We benchmark agents based on Claude v1.0, Claude v2.1, Claude v3 Opus, GPT-4, GPT-4-turbo, Gemini-Pro, and Mixtral and find that a Claude v3 Opus agent is the best in terms of success rate. It can build compelling ML models over many tasks in MLAgentBench with 37.5% average success rate. Our agents also display highly interpretable plans and actions. However, the success rates vary considerably; they span from 100% on well-established older datasets to as low as 0% on recent Kaggle challenges created potentially after the underlying LM was trained. Finally, we identify several key challenges for LM-based agents such as long-term planning and reducing hallucination. Our code is released at https://github.com/snap-stanford/MLAgentBench.</summary> | ||||
| 17 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2023-10-05T04:06:12Z</published> | ||||
| 20 | + <arxiv:primary_category term="cs.LG"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Qian Huang</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Jian Vora</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Percy Liang</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Jure Leskovec</name> | ||||
| 32 | + </author> | ||||
| 33 | + </entry> | ||||
| 34 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2310_06770
+45 −0
@@ -0,0 +1,45 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/QIhoR7/yEQwtzvSiZjqonkYPHXM</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2310.06770&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:29:59Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2310.06770" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2310.06770v3</id> | ||||
| 12 | + <title>SWE-bench: Can Language Models Resolve Real-World GitHub Issues?</title> | ||||
| 13 | + <updated>2024-11-11T23:05:04Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2310.06770v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2310.06770v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Language models have outpaced our ability to evaluate them effectively, but for their future development it is essential to study the frontier of their capabilities. We find real-world software engineering to be a rich, sustainable, and challenging testbed for evaluating the next generation of language models. To this end, we introduce SWE-bench, an evaluation framework consisting of $2,294$ software engineering problems drawn from real GitHub issues and corresponding pull requests across $12$ popular Python repositories. Given a codebase along with a description of an issue to be resolved, a language model is tasked with editing the codebase to address the issue. Resolving issues in SWE-bench frequently requires understanding and coordinating changes across multiple functions, classes, and even files simultaneously, calling for models to interact with execution environments, process extremely long contexts and perform complex reasoning that goes far beyond traditional code generation tasks. Our evaluations show that both state-of-the-art proprietary models and our fine-tuned model SWE-Llama can resolve only the simplest issues. The best-performing model, Claude 2, is able to solve a mere $1.96$% of the issues. Advances on SWE-bench represent steps towards LMs that are more practical, intelligent, and autonomous.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.SE" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2023-10-10T16:47:29Z</published> | ||||
| 21 | + <arxiv:comment>Data, code, and leaderboard are available at https://www.swebench.com ICLR 2024, https://openreview.net/forum?id=VTF8yNQM66</arxiv:comment> | ||||
| 22 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 23 | + <author> | ||||
| 24 | + <name>Carlos E. Jimenez</name> | ||||
| 25 | + </author> | ||||
| 26 | + <author> | ||||
| 27 | + <name>John Yang</name> | ||||
| 28 | + </author> | ||||
| 29 | + <author> | ||||
| 30 | + <name>Alexander Wettig</name> | ||||
| 31 | + </author> | ||||
| 32 | + <author> | ||||
| 33 | + <name>Shunyu Yao</name> | ||||
| 34 | + </author> | ||||
| 35 | + <author> | ||||
| 36 | + <name>Kexin Pei</name> | ||||
| 37 | + </author> | ||||
| 38 | + <author> | ||||
| 39 | + <name>Ofir Press</name> | ||||
| 40 | + </author> | ||||
| 41 | + <author> | ||||
| 42 | + <name>Karthik Narasimhan</name> | ||||
| 43 | + </author> | ||||
| 44 | + </entry> | ||||
| 45 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2401_05507
+74 −0
@@ -0,0 +1,74 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/RpwD5y81NYTHiX7G7Ofwq/XOpfs</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2401.05507&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:32:24Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2401.05507" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2401.05507v3</id> | ||||
| 12 | + <title>InfiAgent-DABench: Evaluating Agents on Data Analysis Tasks</title> | ||||
| 13 | + <updated>2024-03-11T07:57:59Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2401.05507v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2401.05507v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>In this paper, we introduce InfiAgent-DABench, the first benchmark specifically designed to evaluate LLM-based agents on data analysis tasks. These tasks require agents to end-to-end solving complex tasks by interacting with an execution environment. This benchmark contains DAEval, a dataset consisting of 257 data analysis questions derived from 52 CSV files, and an agent framework which incorporates LLMs to serve as data analysis agents for both serving and evaluation. Since data analysis questions are often open-ended and hard to evaluate without human supervision, we adopt a format-prompting technique to convert each question into a closed-form format so that they can be automatically evaluated. Our extensive benchmarking of 34 LLMs uncovers the current challenges encountered in data analysis tasks. In addition, building on top of our agent framework, we develop a specialized agent, DAAgent, which surpasses GPT-3.5 by 3.9% on DABench. Evaluation datasets and toolkits for InfiAgent-DABench are released at https://github.com/InfiAgent/InfiAgent .</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2024-01-10T19:04:00Z</published> | ||||
| 20 | + <arxiv:comment>27 pages, 7 figures, work in progress</arxiv:comment> | ||||
| 21 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Xueyu Hu</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Ziyu Zhao</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Shuang Wei</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Ziwei Chai</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Qianli Ma</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>Guoyin Wang</name> | ||||
| 39 | + </author> | ||||
| 40 | + <author> | ||||
| 41 | + <name>Xuwu Wang</name> | ||||
| 42 | + </author> | ||||
| 43 | + <author> | ||||
| 44 | + <name>Jing Su</name> | ||||
| 45 | + </author> | ||||
| 46 | + <author> | ||||
| 47 | + <name>Jingjing Xu</name> | ||||
| 48 | + </author> | ||||
| 49 | + <author> | ||||
| 50 | + <name>Ming Zhu</name> | ||||
| 51 | + </author> | ||||
| 52 | + <author> | ||||
| 53 | + <name>Yao Cheng</name> | ||||
| 54 | + </author> | ||||
| 55 | + <author> | ||||
| 56 | + <name>Jianbo Yuan</name> | ||||
| 57 | + </author> | ||||
| 58 | + <author> | ||||
| 59 | + <name>Jiwei Li</name> | ||||
| 60 | + </author> | ||||
| 61 | + <author> | ||||
| 62 | + <name>Kun Kuang</name> | ||||
| 63 | + </author> | ||||
| 64 | + <author> | ||||
| 65 | + <name>Yang Yang</name> | ||||
| 66 | + </author> | ||||
| 67 | + <author> | ||||
| 68 | + <name>Hongxia Yang</name> | ||||
| 69 | + </author> | ||||
| 70 | + <author> | ||||
| 71 | + <name>Fei Wu</name> | ||||
| 72 | + </author> | ||||
| 73 | + </entry> | ||||
| 74 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2404_07738
+36 −0
@@ -0,0 +1,36 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/k2nqJO8VKKyQTKeUuVoZ3rCaqME</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2404.07738&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:48:46Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2404.07738" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2404.07738v2</id> | ||||
| 12 | + <title>ResearchAgent: Iterative Research Idea Generation over Scientific Literature with Large Language Models</title> | ||||
| 13 | + <updated>2025-02-09T08:15:44Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2404.07738v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2404.07738v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>The pace of scientific research, vital for improving human life, is complex, slow, and needs specialized expertise. Meanwhile, novel, impactful research often stems from both a deep understanding of prior work, and a cross-pollination of ideas across domains and fields. To enhance the productivity of researchers, we propose ResearchAgent, which leverages the encyclopedic knowledge and linguistic reasoning capabilities of Large Language Models (LLMs) to assist them in their work. This system automatically defines novel problems, proposes methods and designs experiments, while iteratively refining them based on the feedback from collaborative LLM-powered reviewing agents. Specifically, starting with a core scientific paper, ResearchAgent is augmented not only with relevant publications by connecting information over an academic graph but also entities retrieved from a knowledge store derived from shared underlying concepts mined across numerous papers. Then, mimicking a scientific approach to improving ideas with peer discussions, we leverage multiple LLM-based ReviewingAgents that provide reviews and feedback via iterative revision processes. These reviewing agents are instantiated with human preference-aligned LLMs whose criteria for evaluation are elicited from actual human judgments via LLM prompting. We experimentally validate our ResearchAgent on scientific publications across multiple disciplines, showing its effectiveness in generating novel, clear, and valid ideas based on both human and model-based evaluation results. Our initial foray into AI-mediated scientific research has important implications for the development of future systems aimed at supporting researchers in their ideation and operationalization of novel work.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2024-04-11T13:36:29Z</published> | ||||
| 21 | + <arxiv:comment>NAACL 2025</arxiv:comment> | ||||
| 22 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 23 | + <author> | ||||
| 24 | + <name>Jinheon Baek</name> | ||||
| 25 | + </author> | ||||
| 26 | + <author> | ||||
| 27 | + <name>Sujay Kumar Jauhar</name> | ||||
| 28 | + </author> | ||||
| 29 | + <author> | ||||
| 30 | + <name>Silviu Cucerzan</name> | ||||
| 31 | + </author> | ||||
| 32 | + <author> | ||||
| 33 | + <name>Sung Ju Hwang</name> | ||||
| 34 | + </author> | ||||
| 35 | + </entry> | ||||
| 36 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2404_17605
+37 −0
@@ -0,0 +1,37 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/MeSpzSePz0VvKsUKXR/2x6NJi70</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2404.17605&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:12:47Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2404.17605" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2404.17605v1</id> | ||||
| 12 | + <title>Autonomous LLM-driven research from data to human-verifiable research papers</title> | ||||
| 13 | + <updated>2024-04-24T23:15:49Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2404.17605v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2404.17605v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>As AI promises to accelerate scientific discovery, it remains unclear whether fully AI-driven research is possible and whether it can adhere to key scientific values, such as transparency, traceability and verifiability. Mimicking human scientific practices, we built data-to-paper, an automation platform that guides interacting LLM agents through a complete stepwise research process, while programmatically back-tracing information flow and allowing human oversight and interactions. In autopilot mode, provided with annotated data alone, data-to-paper raised hypotheses, designed research plans, wrote and debugged analysis codes, generated and interpreted results, and created complete and information-traceable research papers. Even though research novelty was relatively limited, the process demonstrated autonomous generation of de novo quantitative insights from data. For simple research goals, a fully-autonomous cycle can create manuscripts which recapitulate peer-reviewed publications without major errors in about 80-90%, yet as goal complexity increases, human co-piloting becomes critical for assuring accuracy. Beyond the process itself, created manuscripts too are inherently verifiable, as information-tracing allows to programmatically chain results, methods and data. Our work thereby demonstrates a potential for AI-driven acceleration of scientific discovery while enhancing, rather than jeopardizing, traceability, transparency and verifiability.</summary> | ||||
| 17 | + <category term="q-bio.OT" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2024-04-24T23:15:49Z</published> | ||||
| 20 | + <arxiv:primary_category term="q-bio.OT"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Tal Ifargan</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Lukas Hafner</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Maor Kern</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Ori Alcalay</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Roy Kishony</name> | ||||
| 35 | + </author> | ||||
| 36 | + </entry> | ||||
| 37 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2407_01214
+38 −0
@@ -0,0 +1,38 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/KbLPOwObRc0y/hTh7GYF8bmpwgY</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2407.01214&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:02Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2407.01214" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2407.01214v3</id> | ||||
| 12 | + <title>Revisiting Random Walks for Learning on Graphs</title> | ||||
| 13 | + <updated>2025-03-05T07:02:28Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2407.01214v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2407.01214v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>We revisit a simple model class for machine learning on graphs, where a random walk on a graph produces a machine-readable record, and this record is processed by a deep neural network to directly make vertex-level or graph-level predictions. We call these stochastic machines random walk neural networks (RWNNs), and through principled analysis, show that we can design them to be isomorphism invariant while capable of universal approximation of graph functions in probability. A useful finding is that almost any kind of record of random walks guarantees probabilistic invariance as long as the vertices are anonymized. This enables us, for example, to record random walks in plain text and adopt a language model to read these text records to solve graph tasks. We further establish a parallelism to message passing neural networks using tools from Markov chain theory, and show that over-smoothing in message passing is alleviated by construction in RWNNs, while over-squashing manifests as probabilistic under-reaching. We empirically demonstrate RWNNs on a range of problems, verifying our theoretical analysis and demonstrating the use of language models for separating strongly regular graphs where 3-WL test fails, and transductive classification on arXiv citation network. Code is available at https://github.com/jw9730/random-walk.</summary> | ||||
| 17 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2024-07-01T11:59:59Z</published> | ||||
| 20 | + <arxiv:comment>51 pages, 14 figures</arxiv:comment> | ||||
| 21 | + <arxiv:primary_category term="cs.LG"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Jinwoo Kim</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Olga Zaghen</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Ayhan Suleymanzade</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Youngmin Ryou</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Seunghoon Hong</name> | ||||
| 36 | + </author> | ||||
| 37 | + </entry> | ||||
| 38 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2407_13168
+113 −0
@@ -0,0 +1,113 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/DYItCH2EApXzOT1TTM068bCutFI</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2407.13168&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:10Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2407.13168" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2407.13168v1</id> | ||||
| 12 | + <title>SciCode: A Research Coding Benchmark Curated by Scientists</title> | ||||
| 13 | + <updated>2024-07-18T05:15:24Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2407.13168v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2407.13168v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Since language models (LMs) now outperform average humans on many challenging tasks, it has become increasingly difficult to develop challenging, high-quality, and realistic evaluations. We address this issue by examining LMs' capabilities to generate code for solving real scientific research problems. Incorporating input from scientists and AI researchers in 16 diverse natural science sub-fields, including mathematics, physics, chemistry, biology, and materials science, we created a scientist-curated coding benchmark, SciCode. The problems in SciCode naturally factorize into multiple subproblems, each involving knowledge recall, reasoning, and code synthesis. In total, SciCode contains 338 subproblems decomposed from 80 challenging main problems. It offers optional descriptions specifying useful scientific background information and scientist-annotated gold-standard solutions and test cases for evaluation. Claude3.5-Sonnet, the best-performing model among those tested, can solve only 4.6% of the problems in the most realistic setting. We believe that SciCode demonstrates both contemporary LMs' progress towards becoming helpful scientific assistants and sheds light on the development and evaluation of scientific AI in the future.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2024-07-18T05:15:24Z</published> | ||||
| 20 | + <arxiv:comment>25 pages, 9 figures, 7 tables</arxiv:comment> | ||||
| 21 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Minyang Tian</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Luyu Gao</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Shizhuo Dylan Zhang</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Xinan Chen</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Cunwei Fan</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>Xuefei Guo</name> | ||||
| 39 | + </author> | ||||
| 40 | + <author> | ||||
| 41 | + <name>Roland Haas</name> | ||||
| 42 | + </author> | ||||
| 43 | + <author> | ||||
| 44 | + <name>Pan Ji</name> | ||||
| 45 | + </author> | ||||
| 46 | + <author> | ||||
| 47 | + <name>Kittithat Krongchon</name> | ||||
| 48 | + </author> | ||||
| 49 | + <author> | ||||
| 50 | + <name>Yao Li</name> | ||||
| 51 | + </author> | ||||
| 52 | + <author> | ||||
| 53 | + <name>Shengyan Liu</name> | ||||
| 54 | + </author> | ||||
| 55 | + <author> | ||||
| 56 | + <name>Di Luo</name> | ||||
| 57 | + </author> | ||||
| 58 | + <author> | ||||
| 59 | + <name>Yutao Ma</name> | ||||
| 60 | + </author> | ||||
| 61 | + <author> | ||||
| 62 | + <name>Hao Tong</name> | ||||
| 63 | + </author> | ||||
| 64 | + <author> | ||||
| 65 | + <name>Kha Trinh</name> | ||||
| 66 | + </author> | ||||
| 67 | + <author> | ||||
| 68 | + <name>Chenyu Tian</name> | ||||
| 69 | + </author> | ||||
| 70 | + <author> | ||||
| 71 | + <name>Zihan Wang</name> | ||||
| 72 | + </author> | ||||
| 73 | + <author> | ||||
| 74 | + <name>Bohao Wu</name> | ||||
| 75 | + </author> | ||||
| 76 | + <author> | ||||
| 77 | + <name>Yanyu Xiong</name> | ||||
| 78 | + </author> | ||||
| 79 | + <author> | ||||
| 80 | + <name>Shengzhu Yin</name> | ||||
| 81 | + </author> | ||||
| 82 | + <author> | ||||
| 83 | + <name>Minhui Zhu</name> | ||||
| 84 | + </author> | ||||
| 85 | + <author> | ||||
| 86 | + <name>Kilian Lieret</name> | ||||
| 87 | + </author> | ||||
| 88 | + <author> | ||||
| 89 | + <name>Yanxin Lu</name> | ||||
| 90 | + </author> | ||||
| 91 | + <author> | ||||
| 92 | + <name>Genglin Liu</name> | ||||
| 93 | + </author> | ||||
| 94 | + <author> | ||||
| 95 | + <name>Yufeng Du</name> | ||||
| 96 | + </author> | ||||
| 97 | + <author> | ||||
| 98 | + <name>Tianhua Tao</name> | ||||
| 99 | + </author> | ||||
| 100 | + <author> | ||||
| 101 | + <name>Ofir Press</name> | ||||
| 102 | + </author> | ||||
| 103 | + <author> | ||||
| 104 | + <name>Jamie Callan</name> | ||||
| 105 | + </author> | ||||
| 106 | + <author> | ||||
| 107 | + <name>Eliu Huerta</name> | ||||
| 108 | + </author> | ||||
| 109 | + <author> | ||||
| 110 | + <name>Hao Peng</name> | ||||
| 111 | + </author> | ||||
| 112 | + </entry> | ||||
| 113 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2408_06292
+41 −0
@@ -0,0 +1,41 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/AkzM9Z2XSzzjwcmiXNfISYREWlg</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2408.06292&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:38:56Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2408.06292" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2408.06292v3</id> | ||||
| 12 | + <title>The AI Scientist: Towards Fully Automated Open-Ended Scientific Discovery</title> | ||||
| 13 | + <updated>2024-09-01T00:41:18Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2408.06292v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2408.06292v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>One of the grand challenges of artificial general intelligence is developing agents capable of conducting scientific research and discovering new knowledge. While frontier models have already been used as aides to human scientists, e.g. for brainstorming ideas, writing code, or prediction tasks, they still conduct only a small part of the scientific process. This paper presents the first comprehensive framework for fully automatic scientific discovery, enabling frontier large language models to perform research independently and communicate their findings. We introduce The AI Scientist, which generates novel research ideas, writes code, executes experiments, visualizes results, describes its findings by writing a full scientific paper, and then runs a simulated review process for evaluation. In principle, this process can be repeated to iteratively develop ideas in an open-ended fashion, acting like the human scientific community. We demonstrate its versatility by applying it to three distinct subfields of machine learning: diffusion modeling, transformer-based language modeling, and learning dynamics. Each idea is implemented and developed into a full paper at a cost of less than $15 per paper. To evaluate the generated papers, we design and validate an automated reviewer, which we show achieves near-human performance in evaluating paper scores. The AI Scientist can produce papers that exceed the acceptance threshold at a top machine learning conference as judged by our automated reviewer. This approach signifies the beginning of a new era in scientific discovery in machine learning: bringing the transformative benefits of AI agents to the entire research process of AI itself, and taking us closer to a world where endless affordable creativity and innovation can be unleashed on the world's most challenging problems. Our code is open-sourced at https://github.com/SakanaAI/AI-Scientist</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2024-08-12T16:58:11Z</published> | ||||
| 21 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Chris Lu</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Cong Lu</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Robert Tjarko Lange</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Jakob Foerster</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Jeff Clune</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>David Ha</name> | ||||
| 39 | + </author> | ||||
| 40 | + </entry> | ||||
| 41 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2408_09667
+70 −0
@@ -0,0 +1,70 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/PXr0zNOcANh5uDlDjd4a3P7lucU</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2408.09667&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:05Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2408.09667" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2408.09667v3</id> | ||||
| 12 | + <title>BLADE: Benchmarking Language Model Agents for Data-Driven Science</title> | ||||
| 13 | + <updated>2025-11-10T06:38:02Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2408.09667v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2408.09667v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Data-driven scientific discovery requires the iterative integration of scientific domain knowledge, statistical expertise, and an understanding of data semantics to make nuanced analytical decisions, e.g., about which variables, transformations, and statistical models to consider. LM-based agents equipped with planning, memory, and code execution capabilities have the potential to support data-driven science. However, evaluating agents on such open-ended tasks is challenging due to multiple valid approaches, partially correct steps, and different ways to express the same decisions. To address these challenges, we present BLADE, a benchmark to automatically evaluate agents' multifaceted approaches to open-ended research questions. BLADE consists of 12 datasets and research questions drawn from existing scientific literature, with ground truth collected from independent analyses by expert data scientists and researchers. To automatically evaluate agent responses, we developed corresponding computational methods to match different representations of analyses to this ground truth. Though language models possess considerable world knowledge, our evaluation shows that they are often limited to basic analyses. However, agents capable of interacting with the underlying data demonstrate improved, but still non-optimal, diversity in their analytical decision making. Our work enables the evaluation of agents for data-driven science and provides researchers deeper insights into agents' analysis approaches.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <published>2024-08-19T02:59:35Z</published> | ||||
| 19 | + <arxiv:comment>EMNLP 2024</arxiv:comment> | ||||
| 20 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Ken Gu</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Ruoxi Shang</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Ruien Jiang</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Keying Kuang</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Richard-John Lin</name> | ||||
| 35 | + </author> | ||||
| 36 | + <author> | ||||
| 37 | + <name>Donghe Lyu</name> | ||||
| 38 | + </author> | ||||
| 39 | + <author> | ||||
| 40 | + <name>Yue Mao</name> | ||||
| 41 | + </author> | ||||
| 42 | + <author> | ||||
| 43 | + <name>Youran Pan</name> | ||||
| 44 | + </author> | ||||
| 45 | + <author> | ||||
| 46 | + <name>Teng Wu</name> | ||||
| 47 | + </author> | ||||
| 48 | + <author> | ||||
| 49 | + <name>Jiaqian Yu</name> | ||||
| 50 | + </author> | ||||
| 51 | + <author> | ||||
| 52 | + <name>Yikun Zhang</name> | ||||
| 53 | + </author> | ||||
| 54 | + <author> | ||||
| 55 | + <name>Tianmai M. Zhang</name> | ||||
| 56 | + </author> | ||||
| 57 | + <author> | ||||
| 58 | + <name>Lanyi Zhu</name> | ||||
| 59 | + </author> | ||||
| 60 | + <author> | ||||
| 61 | + <name>Mike A. Merrill</name> | ||||
| 62 | + </author> | ||||
| 63 | + <author> | ||||
| 64 | + <name>Jeffrey Heer</name> | ||||
| 65 | + </author> | ||||
| 66 | + <author> | ||||
| 67 | + <name>Tim Althoff</name> | ||||
| 68 | + </author> | ||||
| 69 | + </entry> | ||||
| 70 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2409_05556
+31 −0
@@ -0,0 +1,31 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/8wt24PYemqez+LyYzMLqqC5oE2E</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2409.05556&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:12:48Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2409.05556" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2409.05556v1</id> | ||||
| 12 | + <title>SciAgents: Automating scientific discovery through multi-agent intelligent graph reasoning</title> | ||||
| 13 | + <updated>2024-09-09T12:25:10Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2409.05556v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2409.05556v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>A key challenge in artificial intelligence is the creation of systems capable of autonomously advancing scientific understanding by exploring novel domains, identifying complex patterns, and uncovering previously unseen connections in vast scientific data. In this work, we present SciAgents, an approach that leverages three core concepts: (1) the use of large-scale ontological knowledge graphs to organize and interconnect diverse scientific concepts, (2) a suite of large language models (LLMs) and data retrieval tools, and (3) multi-agent systems with in-situ learning capabilities. Applied to biologically inspired materials, SciAgents reveals hidden interdisciplinary relationships that were previously considered unrelated, achieving a scale, precision, and exploratory power that surpasses traditional human-driven research methods. The framework autonomously generates and refines research hypotheses, elucidating underlying mechanisms, design principles, and unexpected material properties. By integrating these capabilities in a modular fashion, the intelligent system yields material discoveries, critique and improve existing hypotheses, retrieve up-to-date data about existing research, and highlights their strengths and limitations. Our case studies demonstrate scalable capabilities to combine generative AI, ontological representations, and multi-agent modeling, harnessing a `swarm of intelligence' similar to biological systems. This provides new avenues for materials discovery and accelerates the development of advanced materials by unlocking Nature's design principles.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cond-mat.dis-nn" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cond-mat.mtrl-sci" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 21 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 22 | + <published>2024-09-09T12:25:10Z</published> | ||||
| 23 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Alireza Ghafarollahi</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Markus J. Buehler</name> | ||||
| 29 | + </author> | ||||
| 30 | + </entry> | ||||
| 31 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2409_07703
+49 −0
@@ -0,0 +1,49 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/MGGpN0dR/Ku28MeYV0VKcM6dcOA</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2409.07703&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:47:21Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2409.07703" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2409.07703v3</id> | ||||
| 12 | + <title>DSBench: How Far Are Data Science Agents from Becoming Data Science Experts?</title> | ||||
| 13 | + <updated>2025-04-11T14:12:58Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2409.07703v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2409.07703v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Large Language Models (LLMs) and Large Vision-Language Models (LVLMs) have demonstrated impressive language/vision reasoning abilities, igniting the recent trend of building agents for targeted applications such as shopping assistants or AI software engineers. Recently, many data science benchmarks have been proposed to investigate their performance in the data science domain. However, existing data science benchmarks still fall short when compared to real-world data science applications due to their simplified settings. To bridge this gap, we introduce DSBench, a comprehensive benchmark designed to evaluate data science agents with realistic tasks. This benchmark includes 466 data analysis tasks and 74 data modeling tasks, sourced from Eloquence and Kaggle competitions. DSBench offers a realistic setting by encompassing long contexts, multimodal task backgrounds, reasoning with large data files and multi-table structures, and performing end-to-end data modeling tasks. Our evaluation of state-of-the-art LLMs, LVLMs, and agents shows that they struggle with most tasks, with the best agent solving only 34.12% of data analysis tasks and achieving a 34.74% Relative Performance Gap (RPG). These findings underscore the need for further advancements in developing more practical, intelligent, and autonomous data science agents.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2024-09-12T02:08:00Z</published> | ||||
| 20 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Liqiang Jing</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Zhehui Huang</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Xiaoyang Wang</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Wenlin Yao</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Wenhao Yu</name> | ||||
| 35 | + </author> | ||||
| 36 | + <author> | ||||
| 37 | + <name>Kaixin Ma</name> | ||||
| 38 | + </author> | ||||
| 39 | + <author> | ||||
| 40 | + <name>Hongming Zhang</name> | ||||
| 41 | + </author> | ||||
| 42 | + <author> | ||||
| 43 | + <name>Xinya Du</name> | ||||
| 44 | + </author> | ||||
| 45 | + <author> | ||||
| 46 | + <name>Dong Yu</name> | ||||
| 47 | + </author> | ||||
| 48 | + </entry> | ||||
| 49 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2409_11363
+39 −0
@@ -0,0 +1,39 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/4MxW1myIzKPHQsowoq6sZyt3yT8</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2409.11363&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:38:56Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2409.11363" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2409.11363v2</id> | ||||
| 12 | + <title>CORE-Bench: Fostering the Credibility of Published Research Through a Computational Reproducibility Agent Benchmark</title> | ||||
| 13 | + <updated>2026-06-22T22:36:12Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2409.11363v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2409.11363v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>AI agents have the potential to aid users on a variety of consequential tasks, including conducting scientific research. To spur the development of useful agents, we need benchmarks that are challenging, but more crucially, directly correspond to real-world tasks of interest. This paper introduces such a benchmark, designed to measure the accuracy of AI agents in tackling a crucial yet surprisingly challenging aspect of scientific research: computational reproducibility. This task, fundamental to the scientific process, involves reproducing the results of a study using the provided code and data. We introduce CORE-Bench (Computational Reproducibility Agent Benchmark), a benchmark consisting of 270 tasks based on 90 scientific papers across three disciplines (computer science, social science, and medicine). Tasks in CORE-Bench consist of three difficulty levels and include both language-only and vision-language tasks. We provide an evaluation system to measure the accuracy of agents in a fast and parallelizable way, saving days of evaluation time for each run compared to a sequential implementation. We evaluated two baseline agents: the general-purpose AutoGPT and a task-specific agent called CORE-Agent. We tested both variants using two underlying language models: GPT-4o and GPT-4o-mini. The best agent achieved an accuracy of 21% on the hardest task, showing the vast scope for improvement in automating routine scientific tasks. Having agents that can reproduce existing work is a necessary step towards building agents that can conduct novel research and could verify and improve the performance of other research agents. We hope that CORE-Bench can improve the state of reproducibility and spur the development of future research agents.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.MA" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2024-09-17T17:13:19Z</published> | ||||
| 21 | + <arxiv:comment>Benchmark harness and code available at http://github.com/siegelz/core-bench</arxiv:comment> | ||||
| 22 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 23 | + <author> | ||||
| 24 | + <name>Zachary S. Siegel</name> | ||||
| 25 | + </author> | ||||
| 26 | + <author> | ||||
| 27 | + <name>Sayash Kapoor</name> | ||||
| 28 | + </author> | ||||
| 29 | + <author> | ||||
| 30 | + <name>Nitya Nadgir</name> | ||||
| 31 | + </author> | ||||
| 32 | + <author> | ||||
| 33 | + <name>Benedikt Stroebl</name> | ||||
| 34 | + </author> | ||||
| 35 | + <author> | ||||
| 36 | + <name>Arvind Narayanan</name> | ||||
| 37 | + </author> | ||||
| 38 | + </entry> | ||||
| 39 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2410_05080
+84 −0
@@ -0,0 +1,84 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/qPSVff2v74F/VCHuPAifVh12vec</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2410.05080&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:39:00Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2410.05080" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2410.05080v3</id> | ||||
| 12 | + <title>ScienceAgentBench: Toward Rigorous Assessment of Language Agents for Data-Driven Scientific Discovery</title> | ||||
| 13 | + <updated>2025-03-31T14:39:44Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2410.05080v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2410.05080v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>The advancements of large language models (LLMs) have piqued growing interest in developing LLM-based language agents to automate scientific discovery end-to-end, which has sparked both excitement and skepticism about their true capabilities. In this work, we call for rigorous assessment of agents on individual tasks in a scientific workflow before making bold claims on end-to-end automation. To this end, we present ScienceAgentBench, a new benchmark for evaluating language agents for data-driven scientific discovery. To ensure the scientific authenticity and real-world relevance of our benchmark, we extract 102 tasks from 44 peer-reviewed publications in four disciplines and engage nine subject matter experts to validate them. We unify the target output for every task to a self-contained Python program file and employ an array of evaluation metrics to examine the generated programs, execution results, and costs. Each task goes through multiple rounds of manual validation by annotators and subject matter experts to ensure its annotation quality and scientific plausibility. We also propose two effective strategies to mitigate data contamination concerns. Using ScienceAgentBench, we evaluate five open-weight and proprietary LLMs, each with three frameworks: direct prompting, OpenHands CodeAct, and self-debug. Given three attempts for each task, the best-performing agent can only solve 32.4% of the tasks independently and 34.3% with expert-provided knowledge. In addition, we evaluate OpenAI o1-preview with direct prompting and self-debug, which can boost the performance to 42.2%, demonstrating the effectiveness of increasing inference-time compute but with more than 10 times the cost of other LLMs. Still, our results underscore the limitations of current language agents in generating code for data-driven discovery, let alone end-to-end automation for scientific research.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2024-10-07T14:33:50Z</published> | ||||
| 21 | + <arxiv:comment>ICLR 2025. 60 pages</arxiv:comment> | ||||
| 22 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 23 | + <author> | ||||
| 24 | + <name>Ziru Chen</name> | ||||
| 25 | + </author> | ||||
| 26 | + <author> | ||||
| 27 | + <name>Shijie Chen</name> | ||||
| 28 | + </author> | ||||
| 29 | + <author> | ||||
| 30 | + <name>Yuting Ning</name> | ||||
| 31 | + </author> | ||||
| 32 | + <author> | ||||
| 33 | + <name>Qianheng Zhang</name> | ||||
| 34 | + </author> | ||||
| 35 | + <author> | ||||
| 36 | + <name>Boshi Wang</name> | ||||
| 37 | + </author> | ||||
| 38 | + <author> | ||||
| 39 | + <name>Botao Yu</name> | ||||
| 40 | + </author> | ||||
| 41 | + <author> | ||||
| 42 | + <name>Yifei Li</name> | ||||
| 43 | + </author> | ||||
| 44 | + <author> | ||||
| 45 | + <name>Zeyi Liao</name> | ||||
| 46 | + </author> | ||||
| 47 | + <author> | ||||
| 48 | + <name>Chen Wei</name> | ||||
| 49 | + </author> | ||||
| 50 | + <author> | ||||
| 51 | + <name>Zitong Lu</name> | ||||
| 52 | + </author> | ||||
| 53 | + <author> | ||||
| 54 | + <name>Vishal Dey</name> | ||||
| 55 | + </author> | ||||
| 56 | + <author> | ||||
| 57 | + <name>Mingyi Xue</name> | ||||
| 58 | + </author> | ||||
| 59 | + <author> | ||||
| 60 | + <name>Frazier N. Baker</name> | ||||
| 61 | + </author> | ||||
| 62 | + <author> | ||||
| 63 | + <name>Benjamin Burns</name> | ||||
| 64 | + </author> | ||||
| 65 | + <author> | ||||
| 66 | + <name>Daniel Adu-Ampratwum</name> | ||||
| 67 | + </author> | ||||
| 68 | + <author> | ||||
| 69 | + <name>Xuhui Huang</name> | ||||
| 70 | + </author> | ||||
| 71 | + <author> | ||||
| 72 | + <name>Xia Ning</name> | ||||
| 73 | + </author> | ||||
| 74 | + <author> | ||||
| 75 | + <name>Song Gao</name> | ||||
| 76 | + </author> | ||||
| 77 | + <author> | ||||
| 78 | + <name>Yu Su</name> | ||||
| 79 | + </author> | ||||
| 80 | + <author> | ||||
| 81 | + <name>Huan Sun</name> | ||||
| 82 | + </author> | ||||
| 83 | + </entry> | ||||
| 84 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2410_07095
+58 −0
@@ -0,0 +1,58 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/s54FKqFVwelnrIYBeDZaLtAcemE</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2410.07095&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:18:00Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2410.07095" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2410.07095v6</id> | ||||
| 12 | + <title>MLE-bench: Evaluating Machine Learning Agents on Machine Learning Engineering</title> | ||||
| 13 | + <updated>2025-02-26T11:57:30Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2410.07095v6" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2410.07095v6" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>We introduce MLE-bench, a benchmark for measuring how well AI agents perform at machine learning engineering. To this end, we curate 75 ML engineering-related competitions from Kaggle, creating a diverse set of challenging tasks that test real-world ML engineering skills such as training models, preparing datasets, and running experiments. We establish human baselines for each competition using Kaggle's publicly available leaderboards. We use open-source agent scaffolds to evaluate several frontier language models on our benchmark, finding that the best-performing setup--OpenAI's o1-preview with AIDE scaffolding--achieves at least the level of a Kaggle bronze medal in 16.9% of competitions. In addition to our main results, we investigate various forms of resource scaling for AI agents and the impact of contamination from pre-training. We open-source our benchmark code (github.com/openai/mle-bench/) to facilitate future research in understanding the ML engineering capabilities of AI agents.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <published>2024-10-09T17:34:27Z</published> | ||||
| 19 | + <arxiv:comment>10 pages, 17 pages appendix. Equal contribution by first seven authors, authors randomized. ICLR version</arxiv:comment> | ||||
| 20 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Jun Shern Chan</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Neil Chowdhury</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Oliver Jaffe</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>James Aung</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Dane Sherburn</name> | ||||
| 35 | + </author> | ||||
| 36 | + <author> | ||||
| 37 | + <name>Evan Mays</name> | ||||
| 38 | + </author> | ||||
| 39 | + <author> | ||||
| 40 | + <name>Giulio Starace</name> | ||||
| 41 | + </author> | ||||
| 42 | + <author> | ||||
| 43 | + <name>Kevin Liu</name> | ||||
| 44 | + </author> | ||||
| 45 | + <author> | ||||
| 46 | + <name>Leon Maksin</name> | ||||
| 47 | + </author> | ||||
| 48 | + <author> | ||||
| 49 | + <name>Tejal Patwardhan</name> | ||||
| 50 | + </author> | ||||
| 51 | + <author> | ||||
| 52 | + <name>Lilian Weng</name> | ||||
| 53 | + </author> | ||||
| 54 | + <author> | ||||
| 55 | + <name>Aleksander Mądry</name> | ||||
| 56 | + </author> | ||||
| 57 | + </entry> | ||||
| 58 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2410_07331
+56 −0
@@ -0,0 +1,56 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/Md59J/P4yi47oea6fbUBbmXKa1E</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2410.07331&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:09Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2410.07331" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2410.07331v2</id> | ||||
| 12 | + <title>DA-Code: Agent Data Science Code Generation Benchmark for Large Language Models</title> | ||||
| 13 | + <updated>2024-10-11T00:53:05Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2410.07331v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2410.07331v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>We introduce DA-Code, a code generation benchmark specifically designed to assess LLMs on agent-based data science tasks. This benchmark features three core elements: First, the tasks within DA-Code are inherently challenging, setting them apart from traditional code generation tasks and demanding advanced coding skills in grounding and planning. Second, examples in DA-Code are all based on real and diverse data, covering a wide range of complex data wrangling and analytics tasks. Third, to solve the tasks, the models must utilize complex data science programming languages, to perform intricate data processing and derive the answers. We set up the benchmark in a controllable and executable environment that aligns with real-world data analysis scenarios and is scalable. The annotators meticulously design the evaluation suite to ensure the accuracy and robustness of the evaluation. We develop the DA-Agent baseline. Experiments show that although the baseline performs better than other existing frameworks, using the current best LLMs achieves only 30.5% accuracy, leaving ample room for improvement. We release our benchmark at https://da-code-bench.github.io.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2024-10-09T18:00:05Z</published> | ||||
| 20 | + <arxiv:comment>EMNLP 2024</arxiv:comment> | ||||
| 21 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Yiming Huang</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Jianwen Luo</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Yan Yu</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Yitong Zhang</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Fangyu Lei</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>Yifan Wei</name> | ||||
| 39 | + </author> | ||||
| 40 | + <author> | ||||
| 41 | + <name>Shizhu He</name> | ||||
| 42 | + </author> | ||||
| 43 | + <author> | ||||
| 44 | + <name>Lifu Huang</name> | ||||
| 45 | + </author> | ||||
| 46 | + <author> | ||||
| 47 | + <name>Xiao Liu</name> | ||||
| 48 | + </author> | ||||
| 49 | + <author> | ||||
| 50 | + <name>Jun Zhao</name> | ||||
| 51 | + </author> | ||||
| 52 | + <author> | ||||
| 53 | + <name>Kang Liu</name> | ||||
| 54 | + </author> | ||||
| 55 | + </entry> | ||||
| 56 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2411_00816
+46 −0
@@ -0,0 +1,46 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/m3jSu+1ZnDZmWmWyZCflfuVPaXQ</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2411.00816&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:12:50Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2411.00816" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2411.00816v3</id> | ||||
| 12 | + <title>CycleResearcher: Improving Automated Research via Automated Review</title> | ||||
| 13 | + <updated>2025-03-08T14:01:34Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2411.00816v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2411.00816v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>The automation of scientific discovery has been a long-standing goal within the research community, driven by the potential to accelerate knowledge creation. While significant progress has been made using commercial large language models (LLMs) as research assistants or idea generators, the possibility of automating the entire research process with open-source LLMs remains largely unexplored. This paper explores the feasibility of using open-source post-trained LLMs as autonomous agents capable of performing the full cycle of automated research and review, from literature review and manuscript preparation to peer review and paper refinement. Our iterative preference training framework consists of CycleResearcher, which conducts research tasks, and CycleReviewer, which simulates the peer review process, providing iterative feedback via reinforcement learning. To train these models, we develop two new datasets, Review-5k and Research-14k, reflecting real-world machine learning research and peer review dynamics. Our results demonstrate that CycleReviewer achieves promising performance with a 26.89\% reduction in mean absolute error (MAE) compared to individual human reviewers in predicting paper scores, indicating the potential of LLMs to effectively assist expert-level research evaluation. In research, the papers generated by the CycleResearcher model achieved a score of 5.36 in simulated peer reviews, showing some competitiveness in terms of simulated review scores compared to the preprint level of 5.24 from human experts, while still having room for improvement compared to the accepted paper level of 5.69. This work represents a significant step toward fully automated scientific inquiry, providing ethical safeguards and exploring AI-driven research capabilities. The code, dataset and model weight are released at https://wengsyx.github.io/Researcher/.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.CY" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 21 | + <published>2024-10-28T08:10:21Z</published> | ||||
| 22 | + <arxiv:comment>Accept in ICLR 2025</arxiv:comment> | ||||
| 23 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Yixuan Weng</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Minjun Zhu</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Guangsheng Bao</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Hongbo Zhang</name> | ||||
| 35 | + </author> | ||||
| 36 | + <author> | ||||
| 37 | + <name>Jindong Wang</name> | ||||
| 38 | + </author> | ||||
| 39 | + <author> | ||||
| 40 | + <name>Yue Zhang</name> | ||||
| 41 | + </author> | ||||
| 42 | + <author> | ||||
| 43 | + <name>Linyi Yang</name> | ||||
| 44 | + </author> | ||||
| 45 | + </entry> | ||||
| 46 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2501_04227
+54 −0
@@ -0,0 +1,54 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/wLcsVuMLt4u8519oaQ1H7SNCbSM</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2501.04227&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:50:44Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2501.04227" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2501.04227v2</id> | ||||
| 12 | + <title>Agent Laboratory: Using LLM Agents as Research Assistants</title> | ||||
| 13 | + <updated>2025-06-17T16:19:14Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2501.04227v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2501.04227v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Historically, scientific discovery has been a lengthy and costly process, demanding substantial time and resources from initial conception to final results. To accelerate scientific discovery, reduce research costs, and improve research quality, we introduce Agent Laboratory, an autonomous LLM-based framework capable of completing the entire research process. This framework accepts a human-provided research idea and progresses through three stages--literature review, experimentation, and report writing to produce comprehensive research outputs, including a code repository and a research report, while enabling users to provide feedback and guidance at each stage. We deploy Agent Laboratory with various state-of-the-art LLMs and invite multiple researchers to assess its quality by participating in a survey, providing human feedback to guide the research process, and then evaluate the final paper. We found that: (1) Agent Laboratory driven by o1-preview generates the best research outcomes; (2) The generated machine learning code is able to achieve state-of-the-art performance compared to existing methods; (3) Human involvement, providing feedback at each stage, significantly improves the overall quality of research; (4) Agent Laboratory significantly reduces research expenses, achieving an 84% decrease compared to previous autonomous research methods. We hope Agent Laboratory enables researchers to allocate more effort toward creative ideation rather than low-level coding and writing, ultimately accelerating scientific discovery.</summary> | ||||
| 17 | + <category term="cs.HC" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 21 | + <published>2025-01-08T01:58:42Z</published> | ||||
| 22 | + <arxiv:primary_category term="cs.HC"/> | ||||
| 23 | + <author> | ||||
| 24 | + <name>Samuel Schmidgall</name> | ||||
| 25 | + </author> | ||||
| 26 | + <author> | ||||
| 27 | + <name>Yusheng Su</name> | ||||
| 28 | + </author> | ||||
| 29 | + <author> | ||||
| 30 | + <name>Ze Wang</name> | ||||
| 31 | + </author> | ||||
| 32 | + <author> | ||||
| 33 | + <name>Ximeng Sun</name> | ||||
| 34 | + </author> | ||||
| 35 | + <author> | ||||
| 36 | + <name>Jialian Wu</name> | ||||
| 37 | + </author> | ||||
| 38 | + <author> | ||||
| 39 | + <name>Xiaodong Yu</name> | ||||
| 40 | + </author> | ||||
| 41 | + <author> | ||||
| 42 | + <name>Jiang Liu</name> | ||||
| 43 | + </author> | ||||
| 44 | + <author> | ||||
| 45 | + <name>Michael Moor</name> | ||||
| 46 | + </author> | ||||
| 47 | + <author> | ||||
| 48 | + <name>Zicheng Liu</name> | ||||
| 49 | + </author> | ||||
| 50 | + <author> | ||||
| 51 | + <name>Emad Barsoum</name> | ||||
| 52 | + </author> | ||||
| 53 | + </entry> | ||||
| 54 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2502_18864
+182 −0
@@ -0,0 +1,182 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/GVgjM2sgxBxOvW5pZNUAb729qA8</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2502.18864&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:39:10Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2502.18864" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2502.18864v2</id> | ||||
| 12 | + <title>Accelerating scientific discovery with Co-Scientist</title> | ||||
| 13 | + <updated>2026-06-29T16:12:47Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2502.18864v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2502.18864v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Scientific discovery is driven by scientists generating novel hypotheses for complex problems that undergo rigorous experimental validation. To augment this process, we introduce Co-Scientist, a multi-agent AI system built on Gemini for structured scientific thinking and hypothesis generation. Co-Scientist aims to help scientists discover new original knowledge. Conditioned on their research objectives and prior scientific evidence, it formulates demonstrably novel research hypotheses for experimental verification. The system's design involves agents continuously generating, critiquing and refining hypotheses accelerated by scaling test-time compute. Key contributions include: (1) a multi-agent architecture with an asynchronous task execution framework for flexible compute scaling; (2) a tournament evolution process for self-improving hypotheses generation. Automated evaluations show continued benefits of test-time compute scaling, improving hypothesis quality over time. While general purpose, we focus the validation in three biomedical applications: drug repurposing, novel target discovery, and explaining mechanisms of anti-microbial resistance. Specifically, Co-Scientist helped identify new drug repurposing candidates and synergistic combination therapies for acute myeloid leukemia, which were validated through in vitro experiments. These real-world validations demonstrate the potential of Co-Scientist to accelerate scientific discovery and usher in an era of AI empowered scientists.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.HC" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 21 | + <category term="physics.soc-ph" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 22 | + <category term="q-bio.OT" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 23 | + <published>2025-02-26T06:17:13Z</published> | ||||
| 24 | + <arxiv:comment>157 pages in total (main 42 pages, supplementary information 115 pages), 4 main figures, 1 main table, 6 extended data figures, 2 extended data tables, 9 supplementary figures, 4 supplementary tables, 37 main references, 117 supplementary references. Nature (2026)</arxiv:comment> | ||||
| 25 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 26 | + <author> | ||||
| 27 | + <name>Juraj Gottweis</name> | ||||
| 28 | + </author> | ||||
| 29 | + <author> | ||||
| 30 | + <name>Wei-Hung Weng</name> | ||||
| 31 | + </author> | ||||
| 32 | + <author> | ||||
| 33 | + <name>Alexander Daryin</name> | ||||
| 34 | + </author> | ||||
| 35 | + <author> | ||||
| 36 | + <name>Tao Tu</name> | ||||
| 37 | + </author> | ||||
| 38 | + <author> | ||||
| 39 | + <name>Petar Sirkovic</name> | ||||
| 40 | + </author> | ||||
| 41 | + <author> | ||||
| 42 | + <name>Artiom Myaskovsky</name> | ||||
| 43 | + </author> | ||||
| 44 | + <author> | ||||
| 45 | + <name>Grzegorz Glowaty</name> | ||||
| 46 | + </author> | ||||
| 47 | + <author> | ||||
| 48 | + <name>Felix Weissenberger</name> | ||||
| 49 | + </author> | ||||
| 50 | + <author> | ||||
| 51 | + <name>Alessio Orlandi</name> | ||||
| 52 | + </author> | ||||
| 53 | + <author> | ||||
| 54 | + <name>Dan Popovici</name> | ||||
| 55 | + </author> | ||||
| 56 | + <author> | ||||
| 57 | + <name>Anil Palepu</name> | ||||
| 58 | + </author> | ||||
| 59 | + <author> | ||||
| 60 | + <name>Keran Rong</name> | ||||
| 61 | + </author> | ||||
| 62 | + <author> | ||||
| 63 | + <name>Ryutaro Tanno</name> | ||||
| 64 | + </author> | ||||
| 65 | + <author> | ||||
| 66 | + <name>Khaled Saab</name> | ||||
| 67 | + </author> | ||||
| 68 | + <author> | ||||
| 69 | + <name>Fan Zhang</name> | ||||
| 70 | + </author> | ||||
| 71 | + <author> | ||||
| 72 | + <name>Jacob Blum</name> | ||||
| 73 | + </author> | ||||
| 74 | + <author> | ||||
| 75 | + <name>Andrew Carroll</name> | ||||
| 76 | + </author> | ||||
| 77 | + <author> | ||||
| 78 | + <name>Kavita Kulkarni</name> | ||||
| 79 | + </author> | ||||
| 80 | + <author> | ||||
| 81 | + <name>Nenad Tomasev</name> | ||||
| 82 | + </author> | ||||
| 83 | + <author> | ||||
| 84 | + <name>Dina Zverinski</name> | ||||
| 85 | + </author> | ||||
| 86 | + <author> | ||||
| 87 | + <name>Ivor Rendulic</name> | ||||
| 88 | + </author> | ||||
| 89 | + <author> | ||||
| 90 | + <name>Elahe Vedadi</name> | ||||
| 91 | + </author> | ||||
| 92 | + <author> | ||||
| 93 | + <name>Florian Hasler</name> | ||||
| 94 | + </author> | ||||
| 95 | + <author> | ||||
| 96 | + <name>Luka Rimanic</name> | ||||
| 97 | + </author> | ||||
| 98 | + <author> | ||||
| 99 | + <name>Marina Boia</name> | ||||
| 100 | + </author> | ||||
| 101 | + <author> | ||||
| 102 | + <name>Ivan Budiselic</name> | ||||
| 103 | + </author> | ||||
| 104 | + <author> | ||||
| 105 | + <name>Ben Feinstein</name> | ||||
| 106 | + </author> | ||||
| 107 | + <author> | ||||
| 108 | + <name>Mathias Bellaiche</name> | ||||
| 109 | + </author> | ||||
| 110 | + <author> | ||||
| 111 | + <name>Tom Sheffer</name> | ||||
| 112 | + </author> | ||||
| 113 | + <author> | ||||
| 114 | + <name>Jan Freyberg</name> | ||||
| 115 | + </author> | ||||
| 116 | + <author> | ||||
| 117 | + <name>Jeremy Ratcliff</name> | ||||
| 118 | + </author> | ||||
| 119 | + <author> | ||||
| 120 | + <name>Ottavia Bertolli</name> | ||||
| 121 | + </author> | ||||
| 122 | + <author> | ||||
| 123 | + <name>Katherine Chou</name> | ||||
| 124 | + </author> | ||||
| 125 | + <author> | ||||
| 126 | + <name>Avinatan Hassidim</name> | ||||
| 127 | + </author> | ||||
| 128 | + <author> | ||||
| 129 | + <name>Burak Gokturk</name> | ||||
| 130 | + </author> | ||||
| 131 | + <author> | ||||
| 132 | + <name>Amin Vahdat</name> | ||||
| 133 | + </author> | ||||
| 134 | + <author> | ||||
| 135 | + <name>Yuan Guan</name> | ||||
| 136 | + </author> | ||||
| 137 | + <author> | ||||
| 138 | + <name>Vikram Dhillon</name> | ||||
| 139 | + </author> | ||||
| 140 | + <author> | ||||
| 141 | + <name>Eeshit Dhaval Vaishnav</name> | ||||
| 142 | + </author> | ||||
| 143 | + <author> | ||||
| 144 | + <name>Byron Lee</name> | ||||
| 145 | + </author> | ||||
| 146 | + <author> | ||||
| 147 | + <name>Tiago R D Costa</name> | ||||
| 148 | + </author> | ||||
| 149 | + <author> | ||||
| 150 | + <name>José R Penadés</name> | ||||
| 151 | + </author> | ||||
| 152 | + <author> | ||||
| 153 | + <name>Gary Peltz</name> | ||||
| 154 | + </author> | ||||
| 155 | + <author> | ||||
| 156 | + <name>Yossi Matias</name> | ||||
| 157 | + </author> | ||||
| 158 | + <author> | ||||
| 159 | + <name>James Manyika</name> | ||||
| 160 | + </author> | ||||
| 161 | + <author> | ||||
| 162 | + <name>Demis Hassabis</name> | ||||
| 163 | + </author> | ||||
| 164 | + <author> | ||||
| 165 | + <name>Yunhan Xu</name> | ||||
| 166 | + </author> | ||||
| 167 | + <author> | ||||
| 168 | + <name>Pushmeet Kohli</name> | ||||
| 169 | + </author> | ||||
| 170 | + <author> | ||||
| 171 | + <name>Annalisa Pawlosky</name> | ||||
| 172 | + </author> | ||||
| 173 | + <author> | ||||
| 174 | + <name>Alan Karthikesalingam</name> | ||||
| 175 | + </author> | ||||
| 176 | + <author> | ||||
| 177 | + <name>Vivek Natarajan</name> | ||||
| 178 | + </author> | ||||
| 179 | + <arxiv:doi>10.1038/s41586-026-10644-y</arxiv:doi> | ||||
| 180 | + <link rel="related" href="https://doi.org/10.1038/s41586-026-10644-y" title="doi"/> | ||||
| 181 | + </entry> | ||||
| 182 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2504_01848
+62 −0
@@ -0,0 +1,62 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/qk2fcRy81tDmrei8MPfc0usc1uQ</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2504.01848&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:48:53Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2504.01848" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2504.01848v3</id> | ||||
| 12 | + <title>PaperBench: Evaluating AI's Ability to Replicate AI Research</title> | ||||
| 13 | + <updated>2025-04-07T12:15:49Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2504.01848v3" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2504.01848v3" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>We introduce PaperBench, a benchmark evaluating the ability of AI agents to replicate state-of-the-art AI research. Agents must replicate 20 ICML 2024 Spotlight and Oral papers from scratch, including understanding paper contributions, developing a codebase, and successfully executing experiments. For objective evaluation, we develop rubrics that hierarchically decompose each replication task into smaller sub-tasks with clear grading criteria. In total, PaperBench contains 8,316 individually gradable tasks. Rubrics are co-developed with the author(s) of each ICML paper for accuracy and realism. To enable scalable evaluation, we also develop an LLM-based judge to automatically grade replication attempts against rubrics, and assess our judge's performance by creating a separate benchmark for judges. We evaluate several frontier models on PaperBench, finding that the best-performing tested agent, Claude 3.5 Sonnet (New) with open-source scaffolding, achieves an average replication score of 21.0%. Finally, we recruit top ML PhDs to attempt a subset of PaperBench, finding that models do not yet outperform the human baseline. We open-source our code (https://github.com/openai/preparedness) to facilitate future research in understanding the AI engineering capabilities of AI agents.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2025-04-02T15:55:24Z</published> | ||||
| 20 | + <arxiv:comment>30 pages, 14 figures</arxiv:comment> | ||||
| 21 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Giulio Starace</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Oliver Jaffe</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Dane Sherburn</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>James Aung</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Jun Shern Chan</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>Leon Maksin</name> | ||||
| 39 | + </author> | ||||
| 40 | + <author> | ||||
| 41 | + <name>Rachel Dias</name> | ||||
| 42 | + </author> | ||||
| 43 | + <author> | ||||
| 44 | + <name>Evan Mays</name> | ||||
| 45 | + </author> | ||||
| 46 | + <author> | ||||
| 47 | + <name>Benjamin Kinsella</name> | ||||
| 48 | + </author> | ||||
| 49 | + <author> | ||||
| 50 | + <name>Wyatt Thompson</name> | ||||
| 51 | + </author> | ||||
| 52 | + <author> | ||||
| 53 | + <name>Johannes Heidecke</name> | ||||
| 54 | + </author> | ||||
| 55 | + <author> | ||||
| 56 | + <name>Amelia Glaese</name> | ||||
| 57 | + </author> | ||||
| 58 | + <author> | ||||
| 59 | + <name>Tejal Patwardhan</name> | ||||
| 60 | + </author> | ||||
| 61 | + </entry> | ||||
| 62 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2504_08066
+47 −0
@@ -0,0 +1,47 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/rx48GpCryLvSdQiJ/j1lpc81AJw</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2504.08066&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:12:39Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2504.08066" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2504.08066v1</id> | ||||
| 12 | + <title>The AI Scientist-v2: Workshop-Level Automated Scientific Discovery via Agentic Tree Search</title> | ||||
| 13 | + <updated>2025-04-10T18:44:41Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2504.08066v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2504.08066v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>AI is increasingly playing a pivotal role in transforming how scientific discoveries are made. We introduce The AI Scientist-v2, an end-to-end agentic system capable of producing the first entirely AI generated peer-review-accepted workshop paper. This system iteratively formulates scientific hypotheses, designs and executes experiments, analyzes and visualizes data, and autonomously authors scientific manuscripts. Compared to its predecessor (v1, Lu et al., 2024 arXiv:2408.06292), The AI Scientist-v2 eliminates the reliance on human-authored code templates, generalizes effectively across diverse machine learning domains, and leverages a novel progressive agentic tree-search methodology managed by a dedicated experiment manager agent. Additionally, we enhance the AI reviewer component by integrating a Vision-Language Model (VLM) feedback loop for iterative refinement of content and aesthetics of the figures. We evaluated The AI Scientist-v2 by submitting three fully autonomous manuscripts to a peer-reviewed ICLR workshop. Notably, one manuscript achieved high enough scores to exceed the average human acceptance threshold, marking the first instance of a fully AI-generated paper successfully navigating a peer review. This accomplishment highlights the growing capability of AI in conducting all aspects of scientific research. We anticipate that further advancements in autonomous scientific discovery technologies will profoundly impact human knowledge generation, enabling unprecedented scalability in research productivity and significantly accelerating scientific breakthroughs, greatly benefiting society at large. We have open-sourced the code at https://github.com/SakanaAI/AI-Scientist-v2 to foster the future development of this transformative technology. We also discuss the role of AI in science, including AI safety.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2025-04-10T18:44:41Z</published> | ||||
| 21 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Yutaro Yamada</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Robert Tjarko Lange</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Cong Lu</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Shengran Hu</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Chris Lu</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>Jakob Foerster</name> | ||||
| 39 | + </author> | ||||
| 40 | + <author> | ||||
| 41 | + <name>Jeff Clune</name> | ||||
| 42 | + </author> | ||||
| 43 | + <author> | ||||
| 44 | + <name>David Ha</name> | ||||
| 45 | + </author> | ||||
| 46 | + </entry> | ||||
| 47 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2505_13400
+53 −0
@@ -0,0 +1,53 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/DYAnozArkeotuCq2byaRVI7nZgc</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2505.13400&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T02:39:15Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2505.13400" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2505.13400v1</id> | ||||
| 12 | + <title>Robin: A multi-agent system for automating scientific discovery</title> | ||||
| 13 | + <updated>2025-05-19T17:36:17Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2505.13400v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2505.13400v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Scientific discovery is driven by the iterative process of background research, hypothesis generation, experimentation, and data analysis. Despite recent advancements in applying artificial intelligence to scientific discovery, no system has yet automated all of these stages in a single workflow. Here, we introduce Robin, the first multi-agent system capable of fully automating the key intellectual steps of the scientific process. By integrating literature search agents with data analysis agents, Robin can generate hypotheses, propose experiments, interpret experimental results, and generate updated hypotheses, achieving a semi-autonomous approach to scientific discovery. By applying this system, we were able to identify a novel treatment for dry age-related macular degeneration (dAMD), the major cause of blindness in the developed world. Robin proposed enhancing retinal pigment epithelium phagocytosis as a therapeutic strategy, and identified and validated a promising therapeutic candidate, ripasudil. Ripasudil is a clinically-used rho kinase (ROCK) inhibitor that has never previously been proposed for treating dAMD. To elucidate the mechanism of ripasudil-induced upregulation of phagocytosis, Robin then proposed and analyzed a follow-up RNA-seq experiment, which revealed upregulation of ABCA1, a critical lipid efflux pump and possible novel target. All hypotheses, experimental plans, data analyses, and data figures in the main text of this report were produced by Robin. As the first AI system to autonomously discover and validate a novel therapeutic candidate within an iterative lab-in-the-loop framework, Robin establishes a new paradigm for AI-driven scientific discovery.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.MA" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <category term="q-bio.QM" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 20 | + <published>2025-05-19T17:36:17Z</published> | ||||
| 21 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 22 | + <author> | ||||
| 23 | + <name>Ali Essam Ghareeb</name> | ||||
| 24 | + </author> | ||||
| 25 | + <author> | ||||
| 26 | + <name>Benjamin Chang</name> | ||||
| 27 | + </author> | ||||
| 28 | + <author> | ||||
| 29 | + <name>Ludovico Mitchener</name> | ||||
| 30 | + </author> | ||||
| 31 | + <author> | ||||
| 32 | + <name>Angela Yiu</name> | ||||
| 33 | + </author> | ||||
| 34 | + <author> | ||||
| 35 | + <name>Caralyn J. Szostkiewicz</name> | ||||
| 36 | + </author> | ||||
| 37 | + <author> | ||||
| 38 | + <name>Jon M. Laurent</name> | ||||
| 39 | + </author> | ||||
| 40 | + <author> | ||||
| 41 | + <name>Muhammed T. Razzak</name> | ||||
| 42 | + </author> | ||||
| 43 | + <author> | ||||
| 44 | + <name>Andrew D. White</name> | ||||
| 45 | + </author> | ||||
| 46 | + <author> | ||||
| 47 | + <name>Michaela M. Hinks</name> | ||||
| 48 | + </author> | ||||
| 49 | + <author> | ||||
| 50 | + <name>Samuel G. Rodriques</name> | ||||
| 51 | + </author> | ||||
| 52 | + </entry> | ||||
| 53 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2505_18705
+34 −0
@@ -0,0 +1,34 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/fcn/o9lEPhwcT6XICZBbR2wPcR0</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2505.18705&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:12:53Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2505.18705" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2505.18705v1</id> | ||||
| 12 | + <title>AI-Researcher: Autonomous Scientific Innovation</title> | ||||
| 13 | + <updated>2025-05-24T13:54:38Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2505.18705v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2505.18705v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>The powerful reasoning capabilities of Large Language Models (LLMs) in mathematics and coding, combined with their ability to automate complex tasks through agentic frameworks, present unprecedented opportunities for accelerating scientific innovation. In this paper, we introduce AI-Researcher, a fully autonomous research system that transforms how AI-driven scientific discovery is conducted and evaluated. Our framework seamlessly orchestrates the complete research pipeline--from literature review and hypothesis generation to algorithm implementation and publication-ready manuscript preparation--with minimal human intervention. To rigorously assess autonomous research capabilities, we develop Scientist-Bench, a comprehensive benchmark comprising state-of-the-art papers across diverse AI research domains, featuring both guided innovation and open-ended exploration tasks. Through extensive experiments, we demonstrate that AI-Researcher achieves remarkable implementation success rates and produces research papers that approach human-level quality. This work establishes new foundations for autonomous scientific innovation that can complement human researchers by systematically exploring solution spaces beyond cognitive limitations.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <published>2025-05-24T13:54:38Z</published> | ||||
| 19 | + <arxiv:comment>Code on github: https://github.com/HKUDS/AI-Researcher</arxiv:comment> | ||||
| 20 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Jiabin Tang</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Lianghao Xia</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Zhonghang Li</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Chao Huang</name> | ||||
| 32 | + </author> | ||||
| 33 | + </entry> | ||||
| 34 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2509_26603
+43 −0
@@ -0,0 +1,43 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/0Ab8/DOxy1iz5LBMkqm3U9gLq+I</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2509.26603&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:13:00Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2509.26603" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2509.26603v1</id> | ||||
| 12 | + <title>DeepScientist: Advancing Frontier-Pushing Scientific Findings Progressively</title> | ||||
| 13 | + <updated>2025-09-30T17:49:32Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2509.26603v1" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2509.26603v1" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>While previous AI Scientist systems can generate novel findings, they often lack the focus to produce scientifically valuable contributions that address pressing human-defined challenges. We introduce DeepScientist, a system designed to overcome this by conducting goal-oriented, fully autonomous scientific discovery over month-long timelines. It formalizes discovery as a Bayesian Optimization problem, operationalized through a hierarchical evaluation process consisting of "hypothesize, verify, and analyze". Leveraging a cumulative Findings Memory, this loop intelligently balances the exploration of novel hypotheses with exploitation, selectively promoting the most promising findings to higher-fidelity levels of validation. Consuming over 20,000 GPU hours, the system generated about 5,000 unique scientific ideas and experimentally validated approximately 1100 of them, ultimately surpassing human-designed state-of-the-art (SOTA) methods on three frontier AI tasks by 183.7\%, 1.9\%, and 7.9\%. This work provides the first large-scale evidence of an AI achieving discoveries that progressively surpass human SOTA on scientific tasks, producing valuable findings that genuinely push the frontier of scientific discovery. To facilitate further research into this process, we will open-source all experimental logs and system code at https://github.com/ResearAI/DeepScientist/.</summary> | ||||
| 17 | + <category term="cs.CL" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <category term="cs.LG" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 19 | + <published>2025-09-30T17:49:32Z</published> | ||||
| 20 | + <arxiv:primary_category term="cs.CL"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Yixuan Weng</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Minjun Zhu</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Qiujie Xie</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Qiyao Sun</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Zhen Lin</name> | ||||
| 35 | + </author> | ||||
| 36 | + <author> | ||||
| 37 | + <name>Sifan Liu</name> | ||||
| 38 | + </author> | ||||
| 39 | + <author> | ||||
| 40 | + <name>Yue Zhang</name> | ||||
| 41 | + </author> | ||||
| 42 | + </entry> | ||||
| 43 | +</feed> | ||||
added
research/verify_cache/https_export_arxiv_org_api_query_id_list_2511_02824
+133 −0
@@ -0,0 +1,133 @@ | |||||
| 1 | +<?xml version='1.0' encoding='UTF-8'?> | ||||
| 2 | +<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:arxiv="http://arxiv.org/schemas/atom" xmlns="http://www.w3.org/2005/Atom"> | ||||
| 3 | + <id>https://arxiv.org/api/rqCFPgR0Y5yFBogkOOtv7hLHZuY</id> | ||||
| 4 | + <title>arXiv Query: search_query=&id_list=2511.02824&start=0&max_results=10</title> | ||||
| 5 | + <updated>2026-10-30T03:12:57Z</updated> | ||||
| 6 | + <link href="https://arxiv.org/api/query?search_query=&start=0&max_results=10&id_list=2511.02824" type="application/atom+xml"/> | ||||
| 7 | + <opensearch:itemsPerPage>10</opensearch:itemsPerPage> | ||||
| 8 | + <opensearch:totalResults>1</opensearch:totalResults> | ||||
| 9 | + <opensearch:startIndex>0</opensearch:startIndex> | ||||
| 10 | + <entry> | ||||
| 11 | + <id>http://arxiv.org/abs/2511.02824v2</id> | ||||
| 12 | + <title>Kosmos: An AI Scientist for Autonomous Discovery</title> | ||||
| 13 | + <updated>2025-11-05T18:26:43Z</updated> | ||||
| 14 | + <link href="https://arxiv.org/abs/2511.02824v2" rel="alternate" type="text/html"/> | ||||
| 15 | + <link href="https://arxiv.org/pdf/2511.02824v2" rel="related" type="application/pdf" title="pdf"/> | ||||
| 16 | + <summary>Data-driven scientific discovery requires iterative cycles of literature search, hypothesis generation, and data analysis. Substantial progress has been made towards AI agents that can automate scientific research, but all such agents remain limited in the number of actions they can take before losing coherence, thus limiting the depth of their findings. Here we present Kosmos, an AI scientist that automates data-driven discovery. Given an open-ended objective and a dataset, Kosmos runs for up to 12 hours performing cycles of parallel data analysis, literature search, and hypothesis generation before synthesizing discoveries into scientific reports. Unlike prior systems, Kosmos uses a structured world model to share information between a data analysis agent and a literature search agent. The world model enables Kosmos to coherently pursue the specified objective over 200 agent rollouts, collectively executing an average of 42,000 lines of code and reading 1,500 papers per run. Kosmos cites all statements in its reports with code or primary literature, ensuring its reasoning is traceable. Independent scientists found 79.4% of statements in Kosmos reports to be accurate, and collaborators reported that a single 20-cycle Kosmos run performed the equivalent of 6 months of their own research time on average. Furthermore, collaborators reported that the number of valuable scientific findings generated scales linearly with Kosmos cycles (tested up to 20 cycles). We highlight seven discoveries made by Kosmos that span metabolomics, materials science, neuroscience, and statistical genetics. Three discoveries independently reproduce findings from preprinted or unpublished manuscripts that were not accessed by Kosmos at runtime, while four make novel contributions to the scientific literature.</summary> | ||||
| 17 | + <category term="cs.AI" scheme="http://arxiv.org/schemas/atom"/> | ||||
| 18 | + <published>2025-11-04T18:50:52Z</published> | ||||
| 19 | + <arxiv:comment>Revision: figure layout changes and minor text edits</arxiv:comment> | ||||
| 20 | + <arxiv:primary_category term="cs.AI"/> | ||||
| 21 | + <author> | ||||
| 22 | + <name>Ludovico Mitchener</name> | ||||
| 23 | + </author> | ||||
| 24 | + <author> | ||||
| 25 | + <name>Angela Yiu</name> | ||||
| 26 | + </author> | ||||
| 27 | + <author> | ||||
| 28 | + <name>Benjamin Chang</name> | ||||
| 29 | + </author> | ||||
| 30 | + <author> | ||||
| 31 | + <name>Mathieu Bourdenx</name> | ||||
| 32 | + </author> | ||||
| 33 | + <author> | ||||
| 34 | + <name>Tyler Nadolski</name> | ||||
| 35 | + </author> | ||||
| 36 | + <author> | ||||
| 37 | + <name>Arvis Sulovari</name> | ||||
| 38 | + </author> | ||||
| 39 | + <author> | ||||
| 40 | + <name>Eric C. Landsness</name> | ||||
| 41 | + </author> | ||||
| 42 | + <author> | ||||
| 43 | + <name>Daniel L. Barabasi</name> | ||||
| 44 | + </author> | ||||
| 45 | + <author> | ||||
| 46 | + <name>Siddharth Narayanan</name> | ||||
| 47 | + </author> | ||||
| 48 | + <author> | ||||
| 49 | + <name>Nicky Evans</name> | ||||
| 50 | + </author> | ||||
| 51 | + <author> | ||||
| 52 | + <name>Shriya Reddy</name> | ||||
| 53 | + </author> | ||||
| 54 | + <author> | ||||
| 55 | + <name>Martha Foiani</name> | ||||
| 56 | + </author> | ||||
| 57 | + <author> | ||||
| 58 | + <name>Aizad Kamal</name> | ||||
| 59 | + </author> | ||||
| 60 | + <author> | ||||
| 61 | + <name>Leah P. Shriver</name> | ||||
| 62 | + </author> | ||||
| 63 | + <author> | ||||
| 64 | + <name>Fang Cao</name> | ||||
| 65 | + </author> | ||||
| 66 | + <author> | ||||
| 67 | + <name>Asmamaw T. Wassie</name> | ||||
| 68 | + </author> | ||||
| 69 | + <author> | ||||
| 70 | + <name>Jon M. Laurent</name> | ||||
| 71 | + </author> | ||||
| 72 | + <author> | ||||
| 73 | + <name>Edwin Melville-Green</name> | ||||
| 74 | + </author> | ||||
| 75 | + <author> | ||||
| 76 | + <name>Mayk Caldas</name> | ||||
| 77 | + </author> | ||||
| 78 | + <author> | ||||
| 79 | + <name>Albert Bou</name> | ||||
| 80 | + </author> | ||||
| 81 | + <author> | ||||
| 82 | + <name>Kaleigh F. Roberts</name> | ||||
| 83 | + </author> | ||||
| 84 | + <author> | ||||
| 85 | + <name>Sladjana Zagorac</name> | ||||
| 86 | + </author> | ||||
| 87 | + <author> | ||||
| 88 | + <name>Timothy C. Orr</name> | ||||
| 89 | + </author> | ||||
| 90 | + <author> | ||||
| 91 | + <name>Miranda E. Orr</name> | ||||
| 92 | + </author> | ||||
| 93 | + <author> | ||||
| 94 | + <name>Kevin J. Zwezdaryk</name> | ||||
| 95 | + </author> | ||||
| 96 | + <author> | ||||
| 97 | + <name>Ali E. Ghareeb</name> | ||||
| 98 | + </author> | ||||
| 99 | + <author> | ||||
| 100 | + <name>Laurie McCoy</name> | ||||
| 101 | + </author> | ||||
| 102 | + <author> | ||||
| 103 | + <name>Bruna Gomes</name> | ||||
| 104 | + </author> | ||||
| 105 | + <author> | ||||
| 106 | + <name>Euan A. Ashley</name> | ||||
| 107 | + </author> | ||||
| 108 | + <author> | ||||
| 109 | + <name>Karen E. Duff</name> | ||||
| 110 | + </author> | ||||
| 111 | + <author> | ||||
| 112 | + <name>Tonio Buonassisi</name> | ||||
| 113 | + </author> | ||||
| 114 | + <author> | ||||
| 115 | + <name>Tom Rainforth</name> | ||||
| 116 | + </author> | ||||
| 117 | + <author> | ||||
| 118 | + <name>Randall J. Bateman</name> | ||||
| 119 | + </author> | ||||
| 120 | + <author> | ||||
| 121 | + <name>Michael Skarlinski</name> | ||||
| 122 | + </author> | ||||
| 123 | + <author> | ||||
| 124 | + <name>Samuel G. Rodriques</name> | ||||
| 125 | + </author> | ||||
| 126 | + <author> | ||||
| 127 | + <name>Michaela M. Hinks</name> | ||||
| 128 | + </author> | ||||
| 129 | + <author> | ||||
| 130 | + <name>Andrew D. White</name> | ||||
| 131 | + </author> | ||||
| 132 | + </entry> | ||||
| 133 | +</feed> | ||||
| 134 | |||||