Production-grade documentation for building modern LLM agent systems across three languages, grounded in peer-reviewed research (24 arXiv papers) and production frameworks.
This collection provides complete, runnable implementation guidance for building sophisticated AI agent systems. Each language section covers the same topics — agent loops, tool systems, memory, RAG, knowledge graphs, event-driven architecture, multi-agent workflows, self-improvement, session persistence, and prompt engineering — using the best idiomatic approaches for that ecosystem.
Source material analyzed:
- Claude Code (TypeScript) — swarm multi-backend (tmux/iTerm2/in-process), bridge remote sessions, 8-layer settings, bash security classifier, worktree isolation, QueryGuard, shell snapshot system
- Gemini CLI (TypeScript) — 1M context, 7-strategy model routing, LLM loop detection, tool output masking, A2A server, PTY/xterm headless, VS Code extension companion
- Claw Code (Python+Rust) — mirrored execution model, streaming typed events, frozen dataclass state, deterministic routing
- Claurst (Rust) — 35+ providers, cross-provider tool abstraction, managed-agent orchestration, AutoDream memory, DAP integration
agent-guidelines/
├── README.md ← This file (master index)
├── 00-research-foundation.md ← 25 arXiv papers with full citations
│
├── 01-overview.md ← Universal architecture index + reading paths
├── 01-core-runtime.md ← §1–4: Agent runtime, component inventory, multi-provider
├── 01-prompts-permissions.md ← §5–6: System prompt construction, 6-mode permission system
├── 01-memory-rag-knowledge.md ← §7–9: Memory tiers (CoALA), memdir, RAG pipelines, KG
├── 01-event-driven-multiagent.md ← §10–11: Event sourcing, CQRS, local multi-agent
├── 01-advanced-patterns.md ← §12–23: Self-improvement, QueryGuard, token budget, read-only validation, session storage
├── 01-config-infra-reference.md ← §15–18: Config schema, Docker infra, research papers
├── 01-planning-hooks.md ← §19–20: Planning mode, hook system (30+ events)
├── 01-sessions-cost-ide.md ← §21–23: Session JSONL, cost tracking, IDE integration
├── 01-distributed-agents.md ← §24: A2A protocol, Agent Card, JWT auth
├── 01-extensions-sdk-mcp.md ← §25–28: LSP, plugin system, SDK API, MCP (6 transports)
├── 01-os-shell-integration.md ← §29–35: PTY, subprocess, bash risk classification, background processes, OS signals
├── 01-external-editor-plan-review.md ← External editor blocking (VSCode/vim), plan review workflow, hook-based review gates
├── 01-blocking-waiting-mechanisms.md ← Complete taxonomy of all 8 blocking categories; accessibility matrix for skills/hooks/plugins/agents
│
├── 02-auth-overview-apikey.md ← §1–3: Auth overview, API key patterns
├── 02-auth-oauth-token-keychain.md ← §4–6: OAuth 2.0 PKCE, token management, keychain storage
├── 02-auth-cloud-api-reference.md ← §7–13: Bedrock, Vertex, multi-cloud, error handling
├── 02-auth-multiprovider.md ← §14: Multi-provider routing and fallback
│
├── 03-minimal-agents.md ← §1–2: Minimal working agents (Python/TS/Rust/Go/Kotlin)
├── 03-production-agents.md ← §3–4: Full REPL agent, streaming, MCP integration
├── 03-utilities-mcp-checklist.md ← §5–13: Utilities, MCP server, production checklist
│
├── 04-todo-task-management.md ← Todo/Task CRUD, storage, state machines, dependency DAGs
│
├── 05-dap-debug-integration.md ← DAP: Debug Adapter Protocol (Python/Node/Rust/Go/Java)
├── 05-web-integration.md ← Web fetch/search: SSRF prevention, rate limiting, HTML→markdown, citations
│
├── 06-swarm-backends.md ← Swarm: tmux/iTerm2/in-process backends, file IPC mailbox, permission sync
│
└─── claude-code-extensions/ ← Claude Code extension development (7 files, deep source analysis)
├── 00-index.md ← Master index: 5 extension types, quick-start by use case
├── 01-skills-commands.md ← Skills: frontmatter, shell injection, conditional/dynamic activation
├── 02-agents.md ← Agents: all frontmatter fields, memory, worktree isolation
├── 03-hooks.md ← Hooks: all 27 events, 4 types, full I/O schemas
├── 04-plugins.md ← Plugins: manifest format, lifecycle, marketplace, built-in API
├── 05-mcp-servers.md ← MCP: 6 transports, OAuth, resource support, writing servers
├── 06-settings-permissions.md ← Settings hierarchy, permission rule syntax, permission modes
├── 07-hidden-techniques.md ← Undocumented: asyncRewake, once-hooks, dynamic skills, agent memory
├── 08-mcp-registration-deep.md ← All 7 registration paths, 4 plugin formats, enterprise policy, .mcp.json traversal
└── 09-mcp-workflow-internals.md ← Connection lifecycle, tool wrapping, OAuth flow, MCPB bundles, elicitation
All 24 papers referenced across the implementation guides.
| Paper | arXiv ID | Year | Key Contribution |
|---|---|---|---|
| ReAct | 2210.03629 | 2022 | Thought→Action→Observation loop; +34% ALFWorld |
| Reflexion | 2303.11366 | 2023 | Verbal RL via episodic reflection buffer; 91% HumanEval |
| OpenHands | 2407.16741 | 2024 | Event-sourced state machine, typed tool system |
| MemGPT | 2310.08560 | 2023 | 3-tier memory (in-context / recall / archival) |
| CoALA | 2309.02427 | 2023 | Working/episodic/semantic/procedural memory taxonomy |
| A-MEM | 2502.12110 | 2025 | Zettelkasten note graph + Ebbinghaus decay; 2× MemGPT |
| Mem0 | 2504.19413 | 2025 | Extract→deduplicate→store→retrieve; 90% token reduction |
| GraphRAG | 2404.16130 | 2024 | Leiden community detection + LLM community summaries |
| HippoRAG | 2405.14831 | 2024 | KG + Personalized PageRank; +20% multi-hop QA |
| LightRAG | 2410.05779 | 2024 | Dual-level retrieval (local entity + global community) |
| PathRAG | 2502.14902 | 2025 | Flow-based path pruning on knowledge graphs |
| Self-RAG | 2310.11511 | 2023 | Reflection tokens [Retrieve][IsRel][IsSup][IsUse] |
| CRAG | 2401.15884 | 2024 | Confidence-scored retrieval: Correct/Ambiguous/Incorrect |
| HyDE | 2212.10496 | 2022 | Hypothetical doc embedding improves retrieval |
| RAG-Fusion | 2402.03367 | 2024 | Multi-query + Reciprocal Rank Fusion |
| ESAA | 2602.23193 | 2026 | Event Sourcing + CQRS for agents; append-only JSONL |
| BGE-M3 | 2402.03216 | 2024 | Unified dense+sparse+multi-vector; 100+ languages |
| ExpeL | 2308.10144 | 2023 | Experience pool (vector DB) + LLM-distilled insights |
| SELF-REFINE | selfrefine.info | 2023 | Generate → critique → refine (capped iterations) |
| CRITIC | 2310.06825 | 2023 | Tool-integrated critique loop for self-correction |
| AutoGen | 2308.08155 | 2023 | Actor model — typed message handlers, pub-sub topics |
| MetaGPT | 2308.00352 | 2023 | SOP pipeline: PRD→Architecture→Code→Tests |
| StreamingLLM | 2309.17453 | 2023 | Attention sink tokens + sliding KV cache; 22.2× speedup |
| LongMemEval | 2410.10813 | 2024 | Decompose sessions to atomic facts for retrieval |
These patterns apply across all three implementations:
Every agent core follows: Thought → Action → Observation → repeat until Final Answer. The loop runs until a terminal condition (final answer, max iterations, timeout, or abort).
- Working memory — current context window (in-context)
- Recall memory — recent sessions, searchable by vector similarity
- Archival memory — all historical data, compressed by atomic facts
State is never mutated in place; it is rebuilt by replaying an append-only event log. Enables: deterministic replay, audit trails, time-travel debugging, and crash recovery.
Query → [HyDE expand] → [Multi-query] → [Dense + Sparse retrieve]
→ [Rerank] → [CRAG confidence gate] → [Context compress] → LLM
All tool calls are gated: Deny rules → Hook overrides → Ask rules → Allow rules → Mode default. Never skip the permission check in production.
Use the right strategy for each token-pressure level:
- MicroCompact (75% fill) — compact only the oldest messages, preserve last N verbatim
- Full Compact (90%) — summarize all but the last 10 messages via a dedicated API call
- ContextCollapse (overflow) — strip content blocks from individual messages in-place
- Circuit breaker — disable compaction after 3 consecutive failures to prevent infinite retry loops
- Tool-result budget — evict the text of oldest tool results when combined length exceeds a char cap (e.g., 50 000 chars), keeping only the tool call metadata
After each agent run (score-gated):
CRITIC verify → SELF-REFINE polish → Quality gate →
ExpeL pool → SkillLibrary (if score ≥ 0.85)
Heuristic: if the last N tool-call fingerprints are identical, the agent is looping. LLM-based: after 30 turns, ask a cheap model with confidence threshold 0.9. On detection: inject a meta-message, then abort or ask the user.
When history tool results exceed a char threshold, replace them with placeholders in the context sent to the LLM. The actual output remains stored locally. Saves tokens without losing the data.
Read-only tools can run in parallel (up to 10× throughput on file-read-heavy turns). Sequential execution is required for write tools to avoid file-write conflicts.
7-strategy composite router: CLI override → permission mode → local classifier → cloud classifier → token count → fallback → default. Most agents need only 3: CLI override → 429/529 fallback → default.
Two mechanisms: tool-based (EnterPlanMode/ExitPlanMode tools, permission enforcement, plan file, user approval gate) for interactive agents; extended thinking (API-level, ephemeral, no approval gate) for automated pipelines. Tool-based plan mode enforces read-only at the permission layer — prompt instructions alone are not sufficient. For Manager-Executor topologies, use a ScratchpadGate to block write tools until the manager emits an unlock phrase in its output stream.
30+ hook event types (PreToolUse, PostToolUse, SessionStart, PreCompact, PermissionRequest, etc.). Four hook types: command (shell stdin/stdout JSON), http (webhook POST), prompt (LLM-evaluated), agent (sub-agent verifier). PreToolUse hooks can ALLOW, DENY, ASK, or replace the tool input. Execution is sequential within a matcher group; first non-allow result wins.
Every message has a parentUuid forming a linked list. Fork at any message to create a conversation branch — the branch is a new .jsonl file with the ancestor chain replayed. Sessions are indexed by sha256(realpath(cwd))[:16]. Archive after 90 days; auto-delete after 365. Use SQLite index for session listing at scale.
Track input, output, cache_read, and cache_write tokens separately per turn. Use a SharedBudget with an atomic lock across all agents in a multi-agent system. React to 429 with retry-after header; react to 529 with exponential backoff (max 60s). Never retry 400/401 — fix the request.
Each remote agent publishes an Agent Card (JSON descriptor: capabilities, input/output schema, endpoint, auth type). Delegate tasks via structured JSON with streaming SSE response. Use A2AResultReassembler to collect append: true artifact chunks. Use short-lived JWT tokens for inter-agent auth. Remote agent failures inject structured error into tool result — never crash the orchestrator.
Agents act as LSP clients (not servers) — spawn language servers (pyright, rust-analyzer, clangd) as subprocesses and query via JSON-RPC over stdio. Expose as a single lsp tool with an operation enum. Use lazy initialization (start servers on first file query, not at session start). Passively receive publishDiagnostics notifications and inject as context. Max file size: 10 MB.
Plugins provide: tools, slash commands, hooks, MCP servers, LSP servers, system prompt fragments. Manifest: plugin.json with capabilities declaration (read_only, write, network, shell, agent). Isolation: hooks and MCP/LSP servers run as subprocesses; skills (prompt fragments) run in-process. Load order: built-in → user-global → project-local. Hot-reload on /reload-plugins.
A public SDK exposes: createSession(), resumeSession(), forkSession(), query() (returns async event stream of text/tool_use/tool_result/cost/done events), custom tool registration via defineTool(), and an MCP server wrapper to expose the agent itself as an MCP tool provider. SDK runs headlessly — no REPL, no stdin required.
6 transport types (stdio, HTTP, SSE, WebSocket, SDK in-process, managed proxy). Initialization: initialize → initialized → tools/list. Tool naming: mcp__{server}__{tool} with underscore normalization. Three resource types: tools (callable), resources (file-like), prompts (templates). OAuth 2.0 via metadata discovery. Status lifecycle: pending → connected → needs-auth → failed → disabled.
Two shell execution modes: PTY (interactive commands, color output, isatty checks) and direct subprocess (scripts, pipelines). Pre-execution bash risk classification (Safe/Moderate/Risky/Dangerous/Forbidden) prevents dangerous commands before they run. Track process groups (negative PID) to kill entire subprocess trees. Session-scoped background process registry with log files in validated tmpDir. Shell snapshot: capture environment once per session, source on every command for consistency. Strip ANSI codes + truncate to 50KB before injecting shell output into LLM context. See: 01-os-shell-integration.md.
Agents act as DAP clients — spawn language-specific adapters (debugpy, dlv, lldb-vscode, node-inspect) as subprocesses and communicate via Content-Length JSON-RPC (same framing as LSP). Standard init sequence: initialize → launch/attach → wait for initialized event → setBreakpoints → configurationDone. Expose as a single debug tool with discriminated union for operations (launch, attach, set_breakpoint, state, evaluate, step_over, stop). Check DapCapabilities before using optional features. Timeout all requests at 10s. See: 05-dap-debug-integration.md.
Block SSRF by resolving hostnames and rejecting private IPs (127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x). Rate-limit per hostname (10 req/60s, LRU window). Transform HTML → markdown, JSON → pretty-print, binary → base64. Normalize GitHub blob URLs to raw.githubusercontent.com. Truncate to 100KB before injecting into context. Cache responses 15 min (LRU, 200 entries). Insert citation markers at byte positions (not char positions). See: 05-web-integration.md.
Register backends (tmux, iTerm2, in-process) via self-registering modules to avoid circular deps. Use AsyncLocalStorage for in-process teammate context isolation (each async call tree gets its own context without globals). File-based mailbox with directory-level lockfile for cross-process IPC. Sequential spawn lock (Mutex) in tmux/iTerm2 prevents race conditions. Permission routing: in-process uses direct leader queue; pane-based uses file IPC (pending/resolved dirs). Per-agent git worktrees with --no-checkout + sparse paths. BoundedUUIDSet (FIFO + Set) for message deduplication on history replay. See: 06-swarm-backends.md.
Highest to lowest: Remote managed (MDM API cache) → MDM system policies (HKLM/plist) → Managed file (managed-settings.json + .d/ drop-ins) → User (~/.claude/settings.json) → Project (.claude/settings.json) → Local (.claude/settings.local.json, gitignored) → Flag (--settings CLI / SDK inline) → Plugin (allowlisted keys only). Arrays concatenate+deduplicate; objects deep-merge; undefined = delete (RFC 7396). Validate permission rules before schema parse to prevent one bad rule poisoning the whole file.
Synchronous state machine (idle → dispatching → running) with generation counter prevents concurrent LLM queries. forceEnd() increments generation, invalidating all in-flight finally blocks from aborted queries. Implements useSyncExternalStore for reactive UI sync. See: 01-advanced-patterns.md §20.
Define tools once; use MessageTransformer trait to convert from canonical (Anthropic) format to each provider's wire format at call time. The same tool definition works with Anthropic, OpenAI, Gemini, Bedrock, Azure, Ollama, etc. Provider registry resolves "provider/model" strings to provider instances at query time.