GUIDE · REFERENCE 11 min ·

The instruction files your coding agent obeysWhat loads, who writes it, what holds

Coding agents treat a set of Markdown files as standing orders, and each tool loads a different set under different rules. In October, Forever Security traced a malicious npm install to one AGENTS.md in a customer's Downloads folder. This page maps what each agent loads and which controls still hold when a file lies.

TL;DR· the answer, in twenty seconds

What happened: Forever Security traced a blocked install of the malicious npm package function-color to a 13 KB AGENTS.md in a customer's ~/Downloads. The file told Codex to add an MCP server to its user config. Nobody knows how the file reached that machine.

The minimum fix: Launch agents from project directories only, read instruction files you did not write, and account for every entry in ~/.codex/config.toml and .claude/settings*.json.

The lesson: An instruction file delivers the attack and a config write makes it last. Put your limits where Markdown cannot edit them: sandboxes, managed settings and egress rules.

This page maps the Markdown files that Claude Code, Codex, Cursor and GitHub Copilot accept as standing orders, after Forever Security traced a malicious npm install to an AGENTS.md in a customer's ~/Downloads.

What the Downloads case proved, and what stayed in a lab

Gal Weizman and Omer Samet published the write-up on October 22, 2026. Forever's product blocked an agent from installing function-color, a known-malicious npm package, and the investigation ended at an AGENTS.md in Downloads. Nobody knew how the file got there. Most of the coverage skips that gap, so keep it in mind: the real delivery route is unknown.

The file ran about 13 KB and read as a dull set of "Engineering Work Guidelines". The attack sat in one section near the end, framed as routine environment setup. Forever describes no hidden Unicode in it. The researchers found the model refuses a short, obvious install request and follows one wrapped in a long engineering document.

Sort the claims by how far each one got before you repeat them:

Claim Status Evidence limit
An AGENTS.md in a customer's Downloads drove an attempted install of function-color Seen in the wild, blocked by Forever's product One vendor's customer report
The Codex chain: the file adds an MCP server to ~/.codex/config.toml, and the server runs an npm install Reproduced by Forever Forever says "more than 90%" of attempts, with no sample size published. Most runs used a harmless calculator stand-in, and the real package ran once in an isolated VM
The Claude Code chain: a CLAUDE.md gets .claude/settings.json written with ANTHROPIC_BASE_URL pointing at another server Lab only Researchers wrote this file, inspired by the attacker's. The agent wrote the settings file "about half the time"
A web page plants the file in Downloads Forever's own proof of concept BleepingComputer confirmed a harmless download only. Nothing ties this route to the real attacker

Once the base URL pointed at their server, the researchers captured an OAuth token and replayed it against the real API. That is account takeover with no code execution on the machine. On the next launch their server could answer as the model, and the client accepted a Bash tool call carrying dangerouslyDisableSandbox, though they did not escape the sandbox. Same-session execution through a prompted subagent worked about a fifth of the time.

One line in the post matters more than either percentage: "The same file that worked in a clean folder failed every time in one full of security notes." The outcome depends on what else the model has read. A failed red-team run tells you about that folder on that day.

Forever reports that about half its customers run an agent inside Downloads. BleepingComputer adds more than 1,300 Claude Code sessions launched there, a figure that does not appear in Forever's post. Both describe one vendor's customers, so read them as a sign the habit exists and do not project them onto the industry.

The researchers write, "There is nothing here for OpenAI or Anthropic to patch." That is their position, and none of the sources I read carries a vendor reply to it. BleepingComputer reports that both vendors advise running agents from the specific project directory. Help Net Security reports npm has removed the package.

Which files each agent loads, and when

These rules come from each vendor's current documentation. They change between releases, so check the version notes in the linked pages before you build policy on them.

Agent Project files User and org files When they load
Claude Code CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md. AGENTS.md only when none of the first three exists in the working directory or above (v2.1.277+) ~/.claude/CLAUDE.md. Managed file at /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) or /etc/claude-code/CLAUDE.md (Linux, WSL) Files at or above the working directory at launch. Subdirectory files when Claude reads, writes or edits a file there
Codex AGENTS.override.md, then AGENTS.md, then names in project_doc_fallback_filenames. At most one per directory AGENTS.override.md, else AGENTS.md, in ~/.codex or CODEX_HOME Walks from the project root, usually the Git root, down to the working directory. Concatenates root first. Default cap 32 KiB (project_doc_max_bytes). With no project root, it checks the working directory alone
Cursor .cursor/rules/*.mdc. AGENTS.md at the root and nested User Rules and Team Rules. Precedence runs Team, Project, User Set by each rule's description, globs and alwaysApply frontmatter
GitHub Copilot .github/copilot-instructions.md, .github/instructions/NAME.instructions.md, AGENTS.md, one root CLAUDE.md or GEMINI.md Outside the repository page cited here applyTo globs select path-specific files. For AGENTS.md, the nearest file wins

Five details in that table change your exposure.

Claude Code looks upward. A CLAUDE.md in any parent of the working directory loads at launch, so a stray file in $HOME reaches every session started below it. @path imports pull in other files, and imports from outside the project get a one-time approval dialog. Claude strips block-level HTML comments before injection, which closes one hiding place. claudeMdExcludes skips files you name, except managed ones. /doctor prompt-audit reviews CLAUDE.md, AGENTS.md, rules, skills, commands and subagents in one pass.

Codex gives the deepest file the last word. Later text overrides earlier text, so a file in a subdirectory can countermand the root rules. The planted 13 KB document fits inside the 32 KiB default with room left. OpenAI's AGENTS.md page says nothing about trust. The statement I found is Forever's: "Codex only obeys an AGENTS.md in a project it trusts. Once you have worked in Downloads, it qualifies." Assume any folder where you ran Codex once still counts.

Copilot code review reads instructions from the pull request's head branch, per GitHub's docs. A pull request can change the instructions used to review that same pull request, so an automated review cannot be the only gate on a change to these files.

Cursor ignores plain .md files in .cursor/rules/, so a team that drops security.md there has written a rule nobody loads. Team Rules outrank project rules, which gives an organization one place a repository cannot override.

AGENTS.md now crosses tools. Codex, Cursor and Copilot read it by name, and Claude Code reads it as a fallback. One planted file can address four agents, and a review that greps for .cursorrules alone misses it.

The CVE index covers the patched bugs in this area, including agents editing their own config and the Claude Code trust-dialog CVEs. This page covers behavior that works as documented.

A Markdown file delivers, a config write persists

An instruction file lasts as long as the session that reads it. Both Forever chains aim at something the agent reloads later.

Codex: the user-level config

OpenAI's advanced config docs say project .codex/ layers load only in trusted projects. Project-local config also ignores openai_base_url, chatgpt_base_url, model_provider, model_providers, notify, profile and profiles, so a planted .codex/config.toml cannot redirect the model. User and system layers load regardless of trust. That design pushes an attacker toward ~/.codex/config.toml, and the real file aimed there: one [mcp_servers.*] entry applies to every Codex session on the machine.

Forever lists five obstacles the chain had to clear: the trust gate, unreliable writes, servers that load only at startup, the network sandbox and a handshake timeout. The payload answers the startup problem with a child codex exec run, which loads the new server inside the same session. It answers the sandbox with a flag. "Codex blocks network access for commands", Forever writes, and the fetch failed until the child ran with --dangerously-bypass-approvals-and-sandbox, a flag the model wrote itself after the file framed it as needed for the install. Search your shell history and agent logs for that flag. A sandbox stops mattering once the agent can start a child process with the sandbox off.

Admins can restrict servers in requirements.toml with an approved list:

[mcp_servers.docs]
identity = { command = "codex-mcp" }

[mcp_servers.remote]
identity = { url = "https://example.com/mcp" }

The same file sets allowed_approval_policies and allowed_sandbox_modes. OpenAI marks the second as legacy and prefers permission profiles on Codex 0.138.0 or later.

Claude Code: project settings and headless runs

Forever's lab chain targeted project .claude/settings.json. Anthropic's list of variables Claude Code ignores in env does not name ANTHROPIC_BASE_URL. That list says "They include", so treat its silence as weak evidence and check your own version with /status.

Anthropic's settings page says permissions.allow rules, additionalDirectories and most env values apply only after you trust the folder. Then read what runs before you trust a folder. If you trusted only a parent folder, or you ran claude -p or the SDK in a folder you never trusted, Claude Code still uses settings-file hooks, the env block and apiKeyHelper. In the -p case it also connects .mcp.json servers without asking. The security page confirms a -p session shows no trust prompt. A headless job pointed at an unreviewed checkout gets the checkout's hooks.

.claude is a protected directory. Writes there prompt in default and acceptEdits, go to the classifier in auto, fail in dontAsk and pass in bypassPermissions. Allow rules cannot pre-approve them. Anthropic documents auto mode as the default starting mode for interactive terminal and VS Code sessions. Forever's post does not say which mode its runs used or whether a trust dialog appeared, so I can't tell you which gate its "about half the time" got past.

Three controls address the write and the redirect. The first two are settings keys:

{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  },
  "allowedProviders": ["anthropic"]
}
  • permissions.blockWritesOutsideWorkingDirectories (v2.1.314+) works from any scope. While it is on, the Write, Edit and NotebookEdit tools refuse settings files in every permission mode, including inside the working directory. It does not bind Bash: Anthropic's security page says a Bash command you approve "can still write anywhere your user account can".
  • allowedProviders (v2.1.285+) is managed scope only, so it belongs in managed settings and does nothing in a project file. Claude Code refuses a session on an unlisted provider at startup, at login and at its next API call. A custom host counts as customEndpoint and needs that entry plus an exact pin in a managed env block.
  • A ConfigChange hook fires when a config file changes during a session and can block the change for every source except policy_settings. InstructionsLoaded fires when a CLAUDE.md or rule loads. It cannot block, so use it as a log.

Audit your own machine

This script reads and prints, and it changes nothing. Pass your project roots as arguments. I ran it against a planted fixture on macOS with the system bash 3.2: it found the instruction files, the [mcp_servers.*] entry, the changed endpoint and a zero-width character, and skipped node_modules. It uses find, grep, sort and python3, and I have not run it on Linux.

#!/usr/bin/env bash
# Read-only. Pass project roots as arguments; defaults to the current directory.
set -u
[ $# -gt 0 ] || set -- "$PWD"
codex_home="${CODEX_HOME:-$HOME/.codex}"
list=$(mktemp)
trap 'rm -f "$list"' EXIT

echo "== Instruction files: read any you did not write"
{
  for f in "$HOME/AGENTS.md" "$HOME/CLAUDE.md" "$HOME/.claude/CLAUDE.md" \
           "$codex_home/AGENTS.md" "$codex_home/AGENTS.override.md"; do
    [ -f "$f" ] && echo "$f"
  done
  for root in "$HOME/Downloads" "$HOME/Desktop" /tmp "$@"; do
    [ -d "$root" ] || continue
    find "$root/" -maxdepth 4 -type f -not -path '*/node_modules/*' \( \
      -name 'AGENTS*.md' -o -name 'CLAUDE*.md' -o -name GEMINI.md \
      -o -name .cursorrules -o -name copilot-instructions.md \
      -o -name '*.instructions.md' -o -name '*.mdc' \
      -o -path '*/.claude/rules/*.md' \) 2>/dev/null
  done
} | sort -u | tee "$list"

echo; echo "== Codex: servers and endpoints in the user config"
[ -f "$codex_home/config.toml" ] && grep -nE \
  '^\[mcp_servers\.|^[[:space:]]*(chatgpt_base_url|openai_base_url)[[:space:]]*=' \
  "$codex_home/config.toml"

echo; echo "== Claude Code: endpoints, hooks and helpers in settings"
for root in "$HOME/Downloads" "$HOME/Desktop" "$@"; do
  [ -d "$root" ] || continue
  find "$root/" -maxdepth 4 -type f -path '*/.claude/settings*.json' 2>/dev/null
done | sort -u | while IFS= read -r f; do
  grep -nHE '"(ANTHROPIC_BASE_URL|apiKeyHelper|hooks)"' "$f"
done
[ -f "$HOME/.claude/settings.json" ] && grep -nHE \
  '"(ANTHROPIC_BASE_URL|apiKeyHelper|hooks)"' "$HOME/.claude/settings.json"

echo; echo "== Invisible format characters in the files listed above"
python3 -I - "$list" <<'PY'
import sys, unicodedata
for path in open(sys.argv[1], encoding="utf-8").read().splitlines():
    try:
        text = open(path, encoding="utf-8", errors="replace").read()
    except OSError:
        continue
    hits = sorted({ord(c) for c in text if unicodedata.category(c) == "Cf"})
    if hits:
        print(path, " ".join(f"U+{h:04X}" for h in hits))
PY
exit 0

A hit needs a human reading it. Your own repository will have hooks, and emoji sequences carry U+200D. The finding that matters is an MCP server you cannot name, or an endpoint you did not set.

Controls that miss this attack

Hidden-character scanning gets the most attention in this area because of Pillar Security's Rules File Backdoor, published March 18, 2025, which hid instructions in Cursor and Copilot rule files with invisible Unicode. Cursor called that the user's responsibility. GitHub added a hidden-Unicode warning on github.com on May 1, 2025. Keep the scan, since it costs nothing. Forever's description gives it nothing to find: the attack was plain English in a long, boring document, and a clean scan says nothing about prose.

CODEOWNERS on instruction files is worth having for your repositories. It covers pull requests, and ~/Downloads has no pull requests.

A line in CLAUDE.md saying "never install unknown packages" sits in the same channel the attacker uses. Anthropic's memory docs call these files "context, not enforced configuration" and point you to a PreToolUse hook when you need a block. Writing the rule down helps with honest mistakes. An attacker's longer document can argue with it.

Command deny rules and shell wrappers have documented holes. Anthropic's permissions page says Read and Edit deny rules do not reach arbitrary subprocesses, and its security page says a deny rule matches the command as written and sends you to the sandbox for network enforcement. Commenters on a November 5 DEV Community post add that a .bashrc wrapper misses IDE sidecars and headless workers, and that regex filters miss python3 -c and node -e.

Prompts depend on a person reading what the agent wants to do. The planted section called itself routine environment setup, and approval prompts have their own limits as a credential control.

Egress filtering half works. Aviatrix, which sells network controls, recommends FQDN filtering and alerts on agent self-configuration. An allowlist stops a redirect to an attacker's host. It does nothing for function-color if registry.npmjs.org is on your list, and most teams need it there, so pair it with a registry policy that blocks known-bad packages.

The cheapest effective control is the dull one. Do not start an agent in a folder that collects other people's files. Chrome, Edge and Firefox save to Downloads by default and only show a notification, per BleepingComputer, while Brave prompts.

A checklist to paste into your runbook

Machine
[ ] Launch agents from a project directory, never ~/Downloads, ~/Desktop, /tmp or $HOME
[ ] Revoke trust on catch-all folders (Claude Code keeps decisions in ~/.claude.json)
[ ] Run the audit script now and after any agent behavior you cannot explain
[ ] Read every AGENTS.md and CLAUDE.md you did not write, through to the last section

Codex
[ ] Account for every [mcp_servers.*] entry in ~/.codex/config.toml
[ ] Confirm chatgpt_base_url and openai_base_url are absent or expected
[ ] Fleet: set an approved mcp_servers list in requirements.toml

Claude Code
[ ] Check .claude/settings*.json for ANTHROPIC_BASE_URL and unfamiliar hooks
[ ] Set permissions.blockWritesOutsideWorkingDirectories to true
[ ] Add a ConfigChange hook that logs or blocks project_settings changes
[ ] Treat claude -p on an unreviewed checkout as running that checkout's hooks and env
[ ] Fleet: set allowedProviders in managed settings

Repositories
[ ] Put every instruction file and agent settings file under CODEOWNERS
[ ] Require a human review on PRs that touch them, since Copilot review reads the PR head

If you find a planted file
[ ] Copy the file with its timestamps before deleting anything
[ ] Search npm logs, lockfiles and global installs for function-color
[ ] Rotate agent logins and every credential that machine could reach
[ ] Treat any machine where the package installed as compromised

The last block follows Forever's advice to rotate credentials and treat a function-color install as the indicator, and Help Net Security's advice to assume the login token leaked. The incident runbook covers rotation order, and the guides on Claude Code settings and MCP config files go deeper on each config surface.

What this means for your stack

Stop launching agents from folders that collect other people's files, then run the audit once today. Save a copy of anything in ~/.codex/config.toml or .claude/settings*.json that you cannot explain, then remove it.

Text an agent reads carries no authority of its own, in either direction. Put policy where Markdown cannot edit it: managed settings, sandboxes and egress rules. Keep long-lived credentials out of the agent's reach, so a hijacked session finds a reference instead of a key. That pattern has a limit, visible in Forever's Claude chain: the agent's own login travels with its API traffic, so the endpoint pin has to cover that case.

hasp is one working implementation of the credential half. curl -fsSL https://gethasp.com/install.sh | sh, hasp setup, connect a project, hand the next session a reference instead of a key. Source-available (FCL-1.0), local-first, macOS and Linux, no account.

Assume one of your agents will read a file somebody else wrote. The controls worth keeping are the ones that still hold after the model has believed it.

Sources· cited above, in one place

NEXT STEP~90 seconds

Stop handing the agent your real keys.

hasp keeps secrets in one local encrypted vault, brokers them into the child process at exec, and never lets the agent read the value.

  • Local, encrypted vault — no account, no cloud, no telemetry by default.
  • Brokered run — agent gets a reference, the child process gets the value.
  • Pre-commit + pre-push hooks catch managed values before they ship.
  • Append-only HMAC audit log answers "did the agent touch the prod token?" in seconds.
→ okvault unlocked · binding ./api
→ okgrant once · pid 88421
→ okagent never read

macOS & Linux. Source-available (FCL-1.0, converts to Apache 2.0). No account.

Browse all clusters· eight threads, one index