Why AI Coding Agents Stay Readable: A Five-Layer Breakdown of Entry Points, Loops, Tools, Permissions, and Prompts

3 hr ago0 views

An AI coding agent that reads code, edits files, runs commands, and answers questions is not just a model Q&A wrapper—it's an execution framework built from cooperating subsystems. This article breaks down such agents into five layers: entry point, agent loop, tool execution, permission control, and system prompts. For each layer, you'll learn its core responsibilities, typical design patterns, common pitfalls, and practical TypeScript examples, so you can build agents that are easier to read, test, and maintain.

1. Why Break an AI Coding Agent into Five Layers

An AI coding agent that can read code, modify files, execute commands, and answer questions is essentially not a simple “model Q&A interface,” but an execution framework completed by multiple cooperating subsystems.

After a user inputs a request, the system typically goes through the following process:

Parse command-line arguments or interactive requests;
Determine the current run mode and working directory;
Build the system instructions and context required by the model;
Call the model to get the next decision;
Parse the tool calls returned by the model;
Check whether these operations have execution permission;
Perform file reads, file edits, or command execution;
Feed tool results back to the model;
Keep looping until the task is completed or the user aborts it.

If all of this logic is crammed into one giant function, the code quickly develops several problems: entry logic gets tangled with business logic, permission checks scatter everywhere, tool implementations become hard to test, prompt changes may break the execution flow, and failures are hard to locate.

A clearer implementation therefore splits the system into five layers:

Layer	Typical Modules	Core Responsibility
Entry layer	Startup file, argument parsing module	Receive input, parse arguments, select run mode
Agent loop layer	Query engine, task scheduling module	Drive the round trips between model calls and tool execution
Tool execution layer	Tool definitions, tool registry, executors	Translate model intent into concrete operations
Permission control layer	Permission policies, approval module	Decide whether an operation is allowed
System prompt layer	Prompt templates, context builders	Organize rules, background, and task constraints

These five layers are not just a way to sort files—they form a clear chain of control. The entry layer handles “how the system starts,” the loop layer handles “how the task progresses,” the tool layer handles “what to do concretely,” the permission layer handles “whether it can be done,” and the prompt layer handles “what the model should base its decisions on.”

2. Layer 1: The Entry Layer Converts External Input into Run State

The entry layer is the boundary between the user and the system. It should not handle complex model calls or file operations directly; it should focus on the startup-phase preparation.

1. What the Entry Layer Typically Does

A complete entry module usually handles:

Reading command-line arguments;
Recognizing interactive mode, one-shot task mode, or resume mode;
Determining the current working directory;
Loading necessary configuration;
Initializing logging, terminal output, and interrupt handling;
Creating the runtime context the agent needs;
Handing control over to the agent loop.

For example, the entry logic can be abstracted as:

async function start(args: string[]) {
  const options = parseArguments(args)
  const workspace = resolveWorkspace(options)
  const config = loadConfig(options, workspace)
  const runtime = createRuntime({
    workspace,
    config,
    output: createOutputChannel(),
  })
  return runAgent(runtime, options.task)
}

The key point: the entry function is only responsible for “preparing the run environment” and “starting the main flow.” It should not decide whether a given file may be modified, nor implement search or command execution itself.

2. Why the Entry Layer Should Stay Thin

The thinner the entry layer, the easier the system is to test and extend. Adding a new run mode later only requires a new startup configuration—no changes to the agent core.

Common run modes include:

Interactive conversation;
Auto-execution after receiving a single task;
Code analysis only, no modifications;
Resuming a previously unfinished task;
Running with restricted permissions.

If the entry layer is tightly coupled with the agent loop, every new mode introduces a flood of conditional branches. When the entry layer only produces a unified set of run parameters and the core loop decides behavior via configuration, the structure stays much more stable.

3. Layer 2: The Agent Loop Is the Control Center of the System

The agent loop coordinates the model and the tools, and it is the most important runtime mechanism of an AI coding agent.

Models rarely complete complex tasks in a single pass. They may first list a directory, read a few files, propose changes, run tests, and then keep adjusting based on test results. The system therefore needs a loop of “model decision → tool execution → result feedback.”

1. A Generic Agent Loop

It can be expressed with the following pseudocode:

async function runAgent(runtime, task) {
  const messages = buildInitialMessages(runtime, task)
  while (!isFinished(messages)) {
    const response = await callModel(messages)
    if (response.type === "final") {
      return response.content
    }
    if (response.type === "tool_call") {
      const result = await executeToolCall(runtime, response.call)
      messages.push(response.message)
      messages.push(toToolMessage(response.call, result))
    }
  }
}

This flow involves several key concepts:

messages: the context visible to the model;
callModel: ask the model for the next decision;
tool_call: the model asks the system to run a tool;
executeToolCall: enter the permission-check and execution stage;
isFinished: decide whether the task is complete.

2. The Loop Layer Should Not Implement Tool Details

The loop layer’s job is “scheduling,” not “executing.” It may know that the model returned a file-read request, but it shouldn’t know which low-level API the file read uses.

If the loop layer directly contains branches like this:

if (name === "read_file") {
  // read the file
} else if (name === "run_command") {
  // run the command
} else if (name === "edit_file") {
  // edit the file
}

the loop function will balloon as tools multiply. A better approach is a tool registry:

const tools = {
  read_file: readFileTool,
  search_text: searchTextTool,
  edit_file: editFileTool,
  run_command: commandTool,
}
async function executeToolCall(runtime, call) {
  const tool = tools[call.name]
  if (!tool) {
    return { ok: false, error: "unknown tool" }
  }
  return tool.execute(runtime, call.input)
}

Now the loop layer only cares about “find the tool and run it,” while the tool layer owns the concrete business logic.

3. What Else the Loop Layer Must Handle

A production-ready agent loop also needs to deal with:

Retries after failed model calls;
Tool execution timeouts;
User-initiated interrupts;
Context length management;
Limits on consecutive failures;
Truncation of oversized tool results;
Three terminal states: task completed, task failed, task canceled.

Context management deserves special attention. Tool results keep getting appended to the message list; without compression or trimming, long tasks can blow up the context. Common techniques include keeping key summaries, truncating repetitive output, passing large file contents in segments, and generating intermediate state snapshots at phase transitions.

4. Layer 3: The Tool Layer Turns Model Intent into Real Operations

The model only produces text or structured call requests; it is the tool layer that actually touches the file system, the terminal, and project resources.

1. Tools Should Have Clear Input/Output Contracts

A well-designed tool usually includes:

A unique name;
A parameter structure;
Validation rules;
A functional description;
An execution function;
A result format;
An error-handling strategy.

For example, a file-read tool can be abstracted as:

const readFileTool = {
  name: "read_file",
  validate(input) {
    return typeof input.path === "string"
  },
  async execute(runtime, input) {
    const path = resolveInsideWorkspace(runtime.workspace, input.path)
    const content = await runtime.fs.readFile(path)
    return {
      ok: true,
      path: input.path,
      content,
    }
  },
}

The tool layer should avoid exposing raw low-level exceptions to the model; instead, convert them into stable, understandable results. Missing files, insufficient permissions, invalid paths, and unrecognized encodings should all be mapped to structured messages with an error type and handling suggestions.

2. Distinguish Read-Only Operations from Side-Effecting Operations

Tools can be grouped by risk:

Read-only tools: reading files, searching content, listing directories;
Low-risk write tools: generating temp files, writing caches;
High-risk write tools: modifying source code, deleting files;
External-impact tools: running commands, network access, changing system state.

This classification helps the permission layer apply different policies. For example, read-only operations can run automatically, file modifications may require user confirmation, and operations affecting external systems may be denied by default.

3. Design Tool Output for Both the Model and Debugging

Tool results must be easy for humans to read and easy for the model to understand. They should include:

Whether the operation succeeded;
Which resources were actually affected;
Key results;
Failure reasons;
Suggested next steps;
Necessary structured fields.

The system should also log tool calls—tool name, parameter summary, execution time, result status, and error messages. But logs must avoid leaking sensitive information such as secrets, tokens, and full environment variables.

5. Layer 4: The Permission Layer Is a Security Boundary, Not an Add-On

An AI coding agent can perform real operations, so permission control is a core architectural component. Permission decisions should not rely on prompts alone, nor be left entirely to the model’s self-restraint.

1. Permission Checks Should Exist Independently

A basic permission flow can be expressed as:

async function executeWithPermission(runtime, call) {
  const decision = await checkPermission({
    tool: call.name,
    input: call.input,
    workspace: runtime.workspace,
  })
  if (decision.type === "deny") {
    return { ok: false, error: "operation denied" }
  }
  if (decision.type === "ask") {
    const approved = await requestUserApproval(call)
    if (!approved) {
      return { ok: false, error: "operation rejected by user" }
    }
  }
  return executeToolCall(runtime, call)
}

The permission layer should evaluate at least:

Operation type;
Target path;
Whether the target lies within the current workspace;
Whether sensitive directories are involved;
Whether existing content would be overwritten;
Whether external resources would be accessed;
Whether explicit user confirmation is required.

2. Path Security Cannot Rely on String Checks Alone

For example, simply checking whether a path starts with the workspace string does not fully prevent path traversal. A more robust approach:

Normalize the path;
Resolve symbolic links;
Convert both the workspace and the target path to absolute paths;
Verify the target is genuinely within the allowed range;
Apply extra restrictions to special directories.

Likewise, command execution should not be controlled by a string blacklist alone. Command arguments may contain redirections, pipes, subcommands, and environment variable expansion, so prefer structured parameters, sandboxed runtimes, and explicit allow policies.

3. Permission Decisions Must Be Explainable

When asking for confirmation, the UI should clearly state:

What operation will be performed;
What the target is;
What impact it may have;
Whether files will be modified or external resources accessed;
How to reject the operation.

“Allow or not” is only the outcome; “why confirmation is needed” matters just as much. An explainable permission mechanism reduces mistakes and makes troubleshooting easier.

6. Layer 5: The System Prompt Layer Defines the Model’s Behavioral Boundaries

The prompt layer is not about concatenating a few strings. It organizes system rules, task goals, environment information, and tool descriptions into a context the model can understand.

1. Prompts Are Usually Composed of Multiple Parts

A complete system prompt may include:

Role definition;
Task goals;
Workspace information;
Current run mode;
Available tools and their limits;
File modification conventions;
Testing and validation requirements;
Safety rules;
Output format requirements.

It can be abstracted as:

function buildSystemPrompt(context) {
  return [
    renderRoleRules(context),
    renderWorkspaceInfo(context.workspace),
    renderToolRules(context.tools),
    renderSafetyRules(context.permissions),
    renderTaskConstraints(context.task),
  ].filter(Boolean).join("\n\n")
}

This segmented design is far easier to modify, test, and reuse than maintaining one giant string.

2. Separate Static Rules from Dynamic Context

Static rules are relatively stable, for example:

Read the relevant content before modifying it;
Never fabricate test results;
State clearly when information is uncertain;
Never perform unauthorized high-risk operations.

Dynamic context changes with the task, for example:

Current working directory;
Files already modified;
Current permission mode;
The most recent tool result;
Constraints added by the user.

Separating the two avoids regenerating large amounts of fixed content on every prompt build and helps you pinpoint whether a problem comes from rules or from context.

3. Prompts Cannot Replace Programmatic Constraints

Prompts can guide the model but do not constitute a real security boundary. Even if a prompt says “never access files outside the workspace,” the tool execution layer must still validate paths; even if a prompt says “ask the user before executing,” the permission layer must still forcibly block high-risk operations.

A reliable system uses defense in depth:

Prompts provide guidance;
Tool parameters provide constraints;
The permission module makes decisions;
The execution environment provides isolation;
The logging system provides auditability.

7. How the Five Layers Form a Complete Execution Chain

Combining the layers above, a typical task flows like this:

User input
   ↓
Entry layer: parse arguments, create runtime context
   ↓
Prompt layer: build system rules and task context
   ↓
Agent loop: call the model and parse the next decision
   ↓
Tool layer: locate the tool, validate parameters, prepare execution
   ↓
Permission layer: allow, deny, or request confirmation
   ↓
Execute tool: read, modify, or run operations
   ↓
Tool result returns to the agent loop
   ↓
Update context and call the model again
   ↓
Output the final result

The value of this flow is that each layer has a single, focused responsibility. When something breaks, you can locate the issue quickly:

Won’t start correctly: check the entry layer;
Model stops progressing: check the loop state and context;
Tool not recognized: check tool registration;
Disallowed operation went through: check the permission layer;
Model repeatedly misunderstands the task: check the prompt and context construction;
Inaccurate execution results: check tool implementations and result formats.

8. How to Further Improve Readability and Maintainability

1. Keep Module Boundaries Stable

Modules should communicate through explicit data structures rather than sharing mutable global state. A runtime context can uniformly hold the workspace, configuration, logs, file interfaces, and permission policies—but each module should only read the fields it needs.

2. Write Independent Tests for Each Layer

At minimum, cover:

Entry argument parsing tests;
Loop state transition tests;
Tool parameter validation tests;
Path and permission policy tests;
Prompt fragment composition tests;
Tool failure and timeout tests;
Flow tests after user rejection.

3. Unify the Error Model

If different modules return errors in completely different formats, the loop layer’s handling complexity grows. Unify them as:

type Result<T> =
  | { ok: true; value: T }
  | {
      ok: false
      code: string
      message: string
      retryable?: boolean
    }

This lets the system distinguish retryable errors, user rejections, parameter errors, and unrecoverable errors.

4. Map Logs to Architectural Layers

Logs should carry a layer identifier, for example:

[entry] mode=interactive workspace=...
[loop] model_request started
[tool] name=read_file
[permission] decision=ask
[tool] result=success duration=...

This helps with development and debugging, and with auditing and replaying issues in production.

Conclusion

An AI coding agent stays readable not because it has little code, but because its responsibility boundaries are clear. The entry layer solves “how to start,” the agent loop solves “how to advance the task,” the tool layer solves “what to execute concretely,” the permission layer solves “which operations are allowed,” and the prompt layer solves “what the model bases its decisions on.”

Together, these five layers form an understandable, testable, extensible execution chain. For any intelligent application that calls models, operates tools, and handles external resources, this layered approach offers broadly applicable guidance: isolate the entry point first, then stabilize the loop; make tools registry-driven, make permissions independent; modularize the prompts—and use programmatic constraints to guard the real security boundary.