gocode: Instructions file for Claude Code

Agent Architecture Guide — gocode

System Design Philosophy

This is not a chatbot with file access. This is an agent operating system. Every design decision optimizes for:

1. Composability — Components compose through interfaces, not inheritance.
2. Isolation — Sub-agents run in independent goroutines with their own contexts.
3. Resilience — Failures are contained. One agent crashing doesn't take down the system.
4. Observability — Every tool call, every permission check, every fallback is traceable.

Core Runtime Loop

User Message → ConversationRuntime.SendUserMessage()
  → buildRequest() (system prompt + session + tools)
  → provider.SendMessage() or provider.StreamMessage()
  → parse response content blocks
  → if tool_use blocks exist:
      → for each tool: authorize → pre-hook → execute → post-hook
      → append tool results to session
      → loop back to provider call
  → if no tool_use blocks: return final response

The loop is bounded by maxIter (default 30). Context cancellation propagates cleanly.

Provider Abstraction

type Provider interface {
    SendMessage(ctx context.Context, req MessageRequest) (*MessageResponse, error)
    StreamMessage(ctx context.Context, req MessageRequest) (<-chan StreamEvent, error)
}

Every LLM backend implements this. The FallbackProvider wraps multiple providers and fails over on 429/5xx. The ModelRouter maps task categories to different FallbackProvider chains.

Tool Execution Pipeline

Tool Call → PermissionPolicy.Authorize()
         → HookRunner.PreToolUse()
         → ToolExecutor.Execute()
         → HookRunner.PostToolUse()
         → Result (with merged hook feedback)

Tools are registered in internal/toolimpl/Registry. Each tool implements:

type ToolExecutor interface {
    Execute(params map[string]interface{}) ToolResult
}

Multi-Agent Orchestration

The orchestrator maintains named sub-agent profiles. Each profile specifies:

• System prompt (role-specific)
• Model category (deep/quick/visual/ultrabrain)
• Tool permissions (subset of available tools)