claude_agent_sdk

# Atom Safety

**Rule:** never create an atom from external or unbounded input at runtime.
The BEAM atom table is capped (about 1,048,576 entries by default) and atoms
are **never garbage-collected**. Turning attacker-, CLI-, JSON-, env-, or
model-registry-derived strings into atoms is a memory-exhaustion / node-crash
vector: one crafted stream of distinct strings can take the node down.

## Banned on untrusted input

- `String.to_atom/1`, `List.to_atom/1`
- `:erlang.binary_to_atom/1,2`, `:erlang.list_to_atom/1`
- interpolated sigil atoms — `:"#{var}"`
- `Jason.decode!(json, keys: :atoms)` (and the Poison equivalent)

## Safe patterns

1. **Static lookup with string fallback** — an explicit map (or `case`) from
   known strings to literal atoms, where unknown input **stays a string**.
   The canonical example in this SDK is `ClaudeAgentSDK.Message` subtype
   handling: a `@system_subtypes` module-attribute map consulted via
   `Map.get(@system_subtypes, subtype, subtype)`. New wire frames must follow
   this pattern — the static map is the whole point.
2. **`String.to_existing_atom/1`** — only when the atom is provably
   pre-defined (for example a whitelist the module itself declares). See
   the private
   <code>ClaudeAgentSDK.Auth.TokenStore.parse_provider/1</code> helper for a
   whitelist variant with an explicit default.
3. **Default string keys** — `Jason.decode/1` without `keys:`; or
   `keys: :atoms!` if atom keys are truly required (existing atoms only).
4. **Keep it a string** — MCP tool names, model IDs, and message subtypes do
   not need to be atoms at all.

## Guardrails in this workspace

Two independent guards run in `mix ci` across `claude_agent_sdk`,
`cli_subprocess_core`, and `agent_session_manager`:

- `Credo.Check.Warning.UnsafeToAtom`, enabled in each repo's `.credo.exs`
  (scoped to `lib/`).
- `scripts/atom_guard.sh` — an `rg` backstop that fails CI if a dynamic-atom
  pattern appears in `lib/` without a same-line `# atom-safe:` review
  annotation.

Reviewed compile-time sites (for example the `Module.concat/2` calls in
the <code>ClaudeAgentSDK.Tool.deftool</code> macro expansion, which are bounded
by the number of `deftool` declarations in source) carry both a
`# atom-safe:` annotation and a `credo:disable-for-next-line` marker.