{"uuid": "6d67b6cc-7952-4375-a01e-d7dd1e4871ad", "vulnerability_lookup_origin": "1a89b78e-f703-45f3-bb86-59eb712668bd", "author": "9f56dd64-161d-43a6-b9c3-555944290a09", "vulnerability": "CVE-2025-59536", "type": "seen", "source": "https://gist.github.com/khandar-william/a1ae7a335157d6a2a1dcb9abe1710327", "content": "# Dive into Claude Code: Core Technical Content\n\nReference: https://arxiv.org/pdf/2604.14228\n\n## Design Principles (Table 1)\n\n| Principle | Values Served | Design Question | Sections |\n|-----------|---------------|----------------|----------|\n| Deny-first with human escalation | Authority, Safety | Should unrecognized actions be allowed, blocked, or escalated to the human? | 5, 8, 9 |\n| Graduated trust spectrum | Authority, Adaptability | Fixed permission level, or a spectrum users traverse over time? | 5 |\n| Defense in depth with layered mechanisms | Safety, Authority, Reliability | Single safety boundary, or multiple overlapping ones using different techniques? | 3, 5 |\n| Externalized programmable policy | Safety, Authority, Adaptability | Hardcoded policy, or externalized configs with lifecycle hooks? | 5, 6 |\n| Context as scarce resource with progressive management | Reliability, Capability | What is the binding resource constraint, and how to manage it: single-pass truncation or graduated pipeline? | 4, 6, 7, 8 |\n| Append-only durable state | Reliability, Authority | Mutable state, checkpoint snapshots, or append-only logs? | 4, 9 |\n| Minimal scaffolding, maximal operational harness | Capability, Reliability | Invest in scaffolding-side reasoning, or operational infrastructure that lets the model reason freely? | 3, 4 |\n| Values over rules | Capability, Authority | Rigid decision procedures, or contextual judgment backed by deterministic guardrails? | 3, 5, 7 |\n| Composable multi-mechanism extensibility | Capability, Adaptability | One unified extension API, or layered mechanisms at different context costs? | 6 |\n| Reversibility-weighted risk assessment | Capability, Safety | Same oversight for all actions, or lighter for reversible and read-only ones? | 4, 5, 8 |\n| Transparent file-based configuration and memory | Adaptability, Authority | Opaque database, embedding-based retrieval, or user-visible version-controllable files? | 7 |\n| Isolated subagent boundaries | Reliability, Safety, Capability | Subagents share the parent's context and permissions, or operate in isolation? | 8 |\n| Graceful recovery and resilience | Reliability, Capability | Fail hard on errors, or silently recover and reserve human attention for unrecoverable situations? | 4, 5 |\n\n## High-Level System Structure (7 components)\n\n1. **User**: Submits prompts, approves permissions, reviews output.\n2. **Interfaces**: Interactive CLI, headless CLI (`claude -p`), Agent SDK, and IDE/Desktop/Browser.\n3. **Agent loop**: `queryLoop()` async generator in `query.ts`.\n4. **Permission system**: Deny-first rule evaluation (`permissions.ts`), auto-mode ML classifier, hook-based interception (`types/hooks.ts`).\n5. **Tools**: Up to 54 built-in tools (19 unconditional, 35 conditional) assembled via `assembleToolPool()` (`tools.ts`), merged with MCP-provided tools.\n6. **State & persistence**: Append-only JSONL session transcripts (`sessionStorage.ts`), global prompt history (`history.ts`), subagent sidechain files.\n7. **Execution environment**: Shell execution with optional sandboxing (`shouldUseSandbox.ts`), filesystem operations, web fetching, MCP server connections.\n\n## Five Subsystem Layers\n\n**Surface layer**: `src/entrypoints/` (SDK entry, coreTypes.ts, controlSchemas.ts, coreSchemas.ts), `src/screens/`, `src/components/` (ink framework).\n\n**Core layer**: `queryLoop()` async generator (`query.ts`), five sequential compaction shapers (`query.ts:365-453`).\n\n**Safety/action layer**: \n- Permission system (`permissions.ts`) with 7 permission modes (`types/permissions.ts`)\n- Auto-mode ML classifier (`yoloClassifier.ts`)\n- Hook pipeline spanning 27 event types (`coreTypes.ts`; output schemas in `types/hooks.ts`)\n- Tool pool assembly via `assembleToolPool()` (`tools.ts`)\n- Shell sandbox (`shouldUseSandbox.ts`)\n- Subagent spawning via `AgentTool` (`AgentTool.tsx`, `runAgent.ts`)\n\n**State layer**:\n- `getSystemContext()` and `getUserContext()` (`context.ts`) - memoized\n- `src/state/` - runtime application state\n- JSONL session transcripts at project-specific paths (`sessionStorage.ts`)\n- Four-level instruction hierarchy (`claudemd.ts`)\n- Sidechain transcripts (`sessionStorage.ts:247`)\n- Resume/fork operations (`conversationRecovery.ts`)\n\n**Backend layer**: `BashTool.tsx`, `PowerShellTool.tsx`, `src/remote/`, MCP client (`services/mcp/client.ts`), 42 tool subdirectories in `src/tools/`\n\n## Seven Independent Safety Layers\n\n1. **Tool pre-filtering** (`tools.ts`): Blanket-denied tools removed from model's view before any call.\n2. **Deny-first rule evaluation** (`permissions.ts`): Deny rules always take precedence over allow rules.\n3. **Permission mode constraints** (`types/permissions.ts`): Active mode determines baseline handling.\n4. **Auto-mode classifier**: ML-based classifier evaluates tool safety.\n5. **Shell sandboxing** (`shouldUseSandbox.ts`): Restricts filesystem and network access.\n6. **Not restoring permissions on resume** (`conversationRecovery.ts`): Session-scoped permissions not restored.\n7. **Hook-based interception** (`types/hooks.ts`): `PreToolUse` hooks modify permission decisions; `PermissionRequest` hooks resolve decisions.\n\n## Seven Permission Modes (`types/permissions.ts`)\n\n1. `plan`: Model must create plan; execution proceeds only after user approval.\n2. `default`: Standard interactive use. Most operations require user approval.\n3. `acceptEdits`: Edits within working directory and certain filesystem shell commands auto-approved.\n4. `auto`: ML-based classifier evaluates requests (gated by `TRANSCRIPT_CLASSIFIER`).\n5. `dontAsk`: No prompting, but deny rules still enforced.\n6. `bypassPermissions`: Skips most permission prompts, but safety-critical checks remain.\n7. `bubble`: Internal-only mode for subagent permission escalation to parent terminal.\n\n## Five Pre-Model Context Shapers (`query.ts` before every model call)\n\n1. **Budget reduction** (`applyToolResultBudget()`): Enforces per-message size limits on tool results, replaces oversized outputs with content references.\n2. **Snip** (`snipCompactIfNeeded()`, gated by `HISTORY_SNIP`): Lightweight trim removing older history segments.\n3. **Microcompact**: Fine-grained compression, always runs time-based path, optionally cache-aware path (gated by `CACHED_MICROCOMPACT`).\n4. **Context collapse** (gated by `CONTEXT_COLLAPSE`): Read-time projection over conversation history; summary messages live in collapse store, not REPL array.\n5. **Auto-compact**: Full model-generated summary via `compactConversation()` in `compact.ts`; fires only when context still exceeds pressure threshold after previous four shapers.\n\n## Four Extension Mechanisms (Section 6)\n\n**MCP servers**: Primary external tool integration. Configured from project, user, local, enterprise scopes. Client supports stdio, SSE, HTTP, WebSocket, SDK, IDE-specific variants.\n\n**Plugins**: Package and distribute bundles of MCP servers, skills, hooks, and commands.\n\n**Skills**: Domain-specific instructions injected into context; only frontmatter descriptions stay in prompt.\n\n**Hooks**: 27 hook events: tool authorization (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied), session lifecycle (SessionStart, SessionEnd, Setup, Stop, StopFailure), user interaction (UserPromptSubmit, Elicitation, ElicitationResult), subagent coordination (SubagentStart, SubagentStop, Teammatedle, TaskCreated, TaskCompleted), context management (PreCompact, PostCompact, InstructionsLoaded, ConfigChange), workspace events (CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove), notifications. Persisted hooks use four command types: `command`, `prompt`, `http`, `agent`.\n\n## CLAUDE.md Four-Level Hierarchy (`claudemd.ts`)\n\n1. **Managed memory** (`/etc/claude-code/CLAUDE.md`): OS-level policy for all users.\n2. **User memory** (`~/claude/CLAUDE.md`): Private global instructions.\n3. **Project memory** (`CLAUDE.md`, `claude/CLAUDE.md`, `.claude/rules/*.md` in project roots): Instructions checked into codebase.\n4. **Local memory** (`CLAUDE.local.md` in project roots): Git-ignored, private project-specific instructions.\n\nMemory files support `@include` directive for modular instruction sets. Syntax variants: `@path`, `@/relative`, `@~/home`, `@/absolute`. Works in leaf text nodes only (not inside code blocks).\n\n## Subagent Types (Section 8)\n\n**Built-in subagents**:\n- **Explore**: primarily read/search-oriented investigation, write/edit tools in deny-list\n- **Plan**: creates structured plans; execution proceeds through standard permission model\n- **General-purpose**: broadly capable, used when explicitly requested\n- **Claude Code Guide**: onboarding and documentation assistance with own permissionMode override\n- **Verification**: validation checks (test suites, linting)\n- **Statustime-setup**: terminal status line configuration\n\n**Custom subagents**: via `.claude/agents/*.md` files; YAML frontmatter specifies description, tools (allowlist), disallowedTools, model, effort, permissionMode, mcpServers, hooks, maxTurns, skills, memory scope, background flag, isolation mode.\n\n## Subagent Isolation Modes (`AgentTool.tsx`)\n\n- **Worktree**: Creates temporary git worktree, subagent gets its own copy of repository\n- **Remote** (internal-only): Launches in remote Claude Code Remote environment, always background\n- **In-process** (default): Shares filesystem with parent but operates in isolated conversation context\n\nPermission override logic (`runAgent.ts`): When subagent defines permissionMode, override applied unless parent already in `bypassPermissions`, `acceptEdits`, or `auto` mode (those always take precedence). Async agents: cascade of `canShowPermissionPrompts` first, then bubble mode, then default (sync show prompts, async do not).\n\n## Session Persistence (`sessionStorage.ts`)\n\nTranscript path: `join(projectDir, ${getSessionId()}.jsonl)`. Three independent persistence channels:\n\n1. **Session transcripts**: Conversation records (user, assistant, attachment, system messages, compaction markers, filehistory snapshots, attribution snapshots, content-replacement records)\n2. **Global prompt history**: `history.jsonl` at Claude configuration home directory (`history.ts`)\n3. **Subagent sidechains**: Separate `.jsonl` + `.meta.json` files per subagent\n\n`compact_boundary` marker records `headUuid`, `anchorUuid`, `tailUuid` via `annotateBoundaryWithPreservedSegment()` (`compact.ts`). Resume/fork (`conversationRecovery.ts`, `commands/branch/branch.ts`) do NOT restore session-scoped permissions.\n\n## Tool Pool Assembly Five-Step Pipeline (`tools.ts`)\n\n1. **Base tool enumeration**: `getAllBaseTools()` returns up to 54 tools (19 always included: BashTool, FileReadTool, AgentTool, SkillTool; 35 conditional)\n2. **Mode filtering**: `getTools()` applies mode-specific filtering; `CLAUDE_CODE_SIMPLE` mode only Bash, Read, Edit\n3. **Deny rule pre-filtering**: `filterToolsByDenyRules()` strips blanket-denied tools\n4. **MCP tool integration**: MCP tools from `appState.mcp.tools` filtered and merged\n5. **Deduplication**: By name, built-in tools take precedence over MCP tools\n\n## Tool Dispatch and Streaming Execution (`StreamingToolExecutor.ts`)\n\n- Sibling abort controller: Fires when any Bash tool errors, immediately terminating other in-flight subprocesses\n- Progress-available signal: Wakes up `getRemainingResults()` consumer when new output ready\n- Results buffered and emitted in order tools were received\n- Concurrent-read, serial-write execution model\n\n## Query Loop Stop Conditions\n\n1. No tool use (model produces only text content)\n2. Max turns (`maxTurns` limit reached)\n3. Context overflow (API returns `prompt_too_long`)\n4. Hook intervention (`PostToolUse` hook sets `hook_stopped_continuation`)\n5. Explicit abort (`abortController` signal fires)\n\n## Recovery Mechanisms\n\n- **Max output tokens escalation**: Up to three recovery attempts per turn (`MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3`)\n- **Reactive compaction** (gated by `REACTIVE_COMPACT`): Summarizes just enough to free space; `hasAttemptedReactiveCompact` flag ensures at most once per turn\n- **Prompt-too-long handling**: First attempts context collapse overflow recovery and reactive compaction\n- **Streaming fallback**: `onStreamingFallback` callback handles streaming API issues\n- **Fallback model**: `fallbackModel` parameter enables switching to alternative model\n\n## 27 Hook Events (`coreTypes.ts`, `types/hooks.ts`)\n\nPermission flow hooks (5):\n- `PreToolUse`: returns `permissionDecision` (deny/ask), `permissionDecisionReason`, `updatedInput`\n- `PostToolUse`: injects `additionalContext`, for MCP tools returns `updatedMCPToolOutput`\n- `PostToolUseFailure`: injects `additionalContext` for error-specific guidance\n- `PermissionDenied`: provides retry guidance after auto-mode denials\n- `PermissionRequest`: returns `allow` or `deny` decision\n\nOther hook types: Session lifecycle, user interaction, subagent coordination, context management, workspace events, notifications.\n\nHook command types: `command` (shell), `prompt` (LLM), `http`, `agent` (agentic verifier), plus non-persistable `callback`.\n\n## MCP Client Transport Types (`services/mcp/client.ts`)\n\nstdio, SSE, HTTP, WebSocket, SDK, sse-ide, ws-ide\n\n## Context Injection Points (late injection after main window constructed)\n\n- Relevant-memory prefetch (`query.ts`)\n- MCP instructions deltas (new or changed server instructions)\n- Agent listing deltas\n- Background agent task notifications\n\n## File Structure Key Files\n\n| File | Size | Responsibility |\n|------|------|----------------|\n| `main.tsx` | 804KB | Entry point, mode dispatch, setup |\n| `query.ts` | 68KB | Core agent loop, 5 context shapers |\n| `QueryEngine.ts` | 47KB | SDK/headless conversation wrapper |\n| `Tool.ts` | 30KB | Tool interface, types, utilities |\n| `history.ts` | 14KB | Global prompt history |\n| `mcp/client.ts` | Large | MCP client (8+ transport variants) |\n| `compact.ts` | Large | Compaction engine |\n| `AgentTool.tsx` | Large | Agent tool, subagent dispatch |\n| `runAgent.ts` | Large | 21-parameter agent lifecycle |\n\n## Conditional Tool Availability Categories (`tools.ts`)\n\n- **Always included**: AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool, SkillTool, WebFetchTool, WebSearchTool\n- **Environment**: GlobTool/GrepTool (unless embedded), ConfigTool (internal-only), PowerShellTool (Windows)\n- **Feature flag**: TaskCreate/Get/Update/List (todoV2), EnterWorktreeTool (worktree), TeamTools (swarms), ToolSearchTool\n- **Null-checked**: SuggestBackgroundPRTool, WebBrowserTool, RemoteTriggerTool, MonitorTool, SleepTool\n\n## Context Window Assembly Sources (Figure 6)\n\n1. System prompt (output style modifications, `--append-system-prompt` flag)\n2. Environment info via `getSystemContext()` (`context.ts`): git status, optional cache-breaking injection\n3. CLAUDE.md hierarchy via `getUserContext()` (`context.ts`)\n4. Path-scoped rules (conditional and directory-matched rules, lazy load)\n5. Auto memory (contextually relevant memory entries prefetched asynchronously)\n6. Tool metadata (skill descriptions, MCP tool names, deferred tool definitions via ToolSearch)\n7. Conversation history (subject to compaction)\n8. Tool results (file reads, command outputs, subagent summaries)\n9. Compact summaries (replacing older history segments)\n\n## Compacted Output Structure (`buildPostCompactMessages()` in `compact.ts`)\n\n```\n[boundaryMarker, ...summaryMessages, ...messagesToKeep, ...attachments, ...hookResults]\n```\n\nBoundary marker annotated with `headUuid`, `anchorUuid`, `tailUuid` via `annotateBoundaryWithPreservedSegment()`.\n\n## `runAgent()` 21 Parameters (`runAgent.ts`)\n\nAgent definition, prompts, permissions, tools, model settings, isolation, callbacks.\n\n## Two-Tier Permission Scoping for Subagents (`runAgent.ts`)\n\n- SDK-level permissions from `allowedTools` preserved (\"explicit permissions from the SDK consumer that should apply to all agents\")\n- Session-level rules replaced with subagent's declared `allowedTools`\n- When `allowedTools` not provided (common AgentTool path), parent's session-level rules inherited without replacement\n\n## Agent Teams Coordination\n\nFile locking rather than message broker or distributed coordination service. Tasks claimed from shared list via lock-file-based mutual exclusion. Lock files stored at predictable filesystem paths.\n\n## Security Vulnerabilities Documented\n\n- Commands with >50 subcommands fall back to single generic approval prompt instead of per-subcommand deny-rule checks (Adversa.ai, 2026)\n- Pre-trust initialization ordering: hooks, MCP server connections, settings file resolution run before interactive trust dialog (Donenfeld and Vanunu, 2026; CVE-2025-59536 CVSS 8.7, CVE-2026-21852 CVSS 5.3)\n- Multiple CVEs exploit pre-trust initialization of hooks and MCP servers\n\n## Empirical Data Points\n\n- 1.6% of codebase constitutes AI decision logic; 98.4% operational infrastructure\n- Users approve approximately 93% of permission prompts (Hughes, 2026)\n- Auto-approve rates increase from ~20% at <50 sessions to >40% by 750 sessions (McCain et al., 2026)\n- Sandboxing reduced permission prompt frequency by estimated 84% (Dworken and Weller-Davies, 2025)\n- Agent teams consume approximately 7\u00d7 tokens of standard session in plan mode (Anthropic, 2025b)\n- 27% of Claude Code-assisted tasks were work not attempted without the tool (Huang et al., 2025)\n- Developers in AI-assisted conditions scored 17% lower on comprehension tests (Shen and Tamkin, 2026)\n- Causal analysis of Cursor adoption across 807 repositories: code complexity increased by 40.7% (He et al., 2025)\n- AI tools made developers 19% slower despite perceived 20% improvement (Becker et al., 2025)\n- 304,000 AI-authored commits across 6,275 repositories: ~25% of AI-introduced issues persist to latest revision (Liu et al., 2026)", "creation_timestamp": "2026-06-15T11:06:36.000000Z"}