How an AI Coding Agent Actually Works

By now we can describe a requirement, break it into verifiable pieces and plan the changes, as covered in decomposition and shaping work, vertical slices, dependency graphs and implementation plans. We have also seen how to turn acceptance criteria and risks into a test plan before any code is written. The next question is what actually happens when a developer hands that work to an AI coding agent. It is not one "clever program". It is a system made of several separate parts: a model, an application, tools, an environment and external services.

The most important practical boundary is this: a message about an action is not an executed action, and an executed action is not proof of a correct result. To know what was really done, you need to see which tools were available, how they were called, what they actually returned, and what state can be checked independently.

Every name, file, requirement, command, result and number in the three worked examples in this unit is invented for teaching purposes. None of them describes a real project or a real test run.

AI, a language model and an agent are different layers

Artificial intelligence (AI) is a broad name for methods and programs that perform tasks we usually associate with human abilities: recognising speech or images, forecasting, planning, generating text. The word "AI" on its own tells you nothing about which algorithm is used or how reliable the result is.

A large language model (LLM) is a model trained to work with language and other sequences of data. Put simply, it receives a context and generates a continuation, estimating which next fragments fit that context best. That is what lets it answer questions, summarise text, suggest code and produce a structured tool call.

This mechanism does not guarantee truth. A model can confidently compose an answer that sounds plausible but rests on a false assumption, outdated knowledge or a file it never saw. Such an invented or unsupported answer is often called a hallucination. The term names a class of errors, not the cause of each one: sometimes the problem lies in the model, sometimes in incomplete context, a poor tool, an environment failure or a misread result.

It is also important not to confuse three different capabilities:

1. The model knows from training what a command or an API usually looks like.
2. The current application has provided a tool that can read or change the system in question.
3. That tool has the permission and the technical ability to perform the action here and now.

The first does not create the second or the third. A model can explain how to open a ticket in Jira, but without an available Jira tool it cannot see your project and cannot create anything in it.

The word agent usually refers to an application that accepts a goal, can choose its next steps, calls tools and uses their results to keep going. An agent may take one step or many; it may stop to ask a question; it may make mistakes. The word describes a way of organising work, not a certificate of autonomy or correctness.

In a coding assistant, the model proposes possible steps, and an external program decides what is actually permitted and executed. The fact that the model produced the text "running the checks" does not, by itself, run anything.

What the system is made of

The words "model", "client", "harness", "tool", "sandbox" and "server" mark different boundaries. They can be packaged into one product, but that does not make them one and the same component.

Part	Plain explanation	What it does not prove on its own
Model	Computes a response from the context it receives.	That code was executed, a file was read or a claim was verified.
Application / client	The interface through which a person sets a task, sees the response and controls the session.	That the application has every capability enabled that some other product has.
Harness	Orchestrates requests to the model, context, tools, permissions, retries, events and the end of the run.	That a particular tool is available, or that any given call to it will be allowed.
Runtime	Actually runs the agent program and its tools.	That the process can see every file on the computer or has network access.
Tool	A single operation: read a file, run a command, find a page, create a record through an integration.	That calling it has already succeeded, or that the result meets the requirement.
Sandbox / environment	The workspace in which tools see files, processes, network, dependencies and limits.	That it holds the same files, versions, network routes or data as the user's machine.
External service	A system outside the agent: for example GitHub, Jira, a database or a cloud application programming interface (API).	That the integration is configured, authenticated, has write permission or returned the expected state.

The application is what a person actually uses: a web page, a desktop program, an editor extension or the command line. It may connect to the model remotely while a separate program on the computer performs local file edits.

The harness (literally the "rigging" around the model; in this unit, the agent's software shell) runs the loop between the person, the model and the tools. It is the part that can add instructions, select a portion of history, pass along tool schemas, show a permission prompt, run a command and return its output. In a small system one process may play all these roles; in a cloud product they are spread across the client, the API and a managed environment.

The runtime is the part of the system that actually executes the agent application and its tools. In one product it is a command-line process on a laptop; in another it is a container in the cloud. The model does not automatically gain access to everything a person sees on screen: access is defined by what the runtime has exposed.

A tool can be very simple or very large. Reading a specific file returns data; a shell command starts a process; an integration might send a message, update a ticket or change settings in another service. When an action has a side effect outside the conversation, its consequences can outlive the agent session itself.

An external service has its own authorisation. Rights to a local repository are not rights to the remote GitHub repository. Read access to Jira is not permission to create issues. The harness allowing a command to run does not make the network reachable. Every boundary has its own settings.

In some systems the external API offers a ready-made tool that runs on the agent vendor's side. In others it only describes the operation, and the developer writes and runs the program that actually calls Jira or GitHub. So the question "where does this tool run?" has to be asked separately from "who described it?" and "what permissions does it have?".

The observable loop: observe, decide, act, inspect, adjust

A convenient teaching model of how an agent works has five phases:

observe → decide → act → inspect → adjust

This loop is not a mandatory protocol of any particular vendor. It helps you track the externally visible events:

1. Observe. The agent receives the request and the context available to it: instructions, files, earlier messages or the result of a previous tool.
2. Decide. The model returns a response or a structured tool request. This is a visible choice of the next operation, not a window into the model's hidden internal monologue.
3. Act. The harness checks the format and the permissions and, where allowed, performs the action.
4. Inspect. The system receives the actual result: file contents, a process exit code, a server error or the identifier of a newly created record. The model can receive this result; a person often sees it in a log or in the interface.
5. Adjust. Based on the result, the agent may continue with another tool, change its hypothesis, ask for clarification, or stop and report a limitation.

If the user only asked for an explanation, the loop may end after the answer. If code needs fixing, it repeats: read the test, examine the file, propose an edit, run the test, read the new result. The exact sequence is shaped by the available tools and the situation, not by one universal script.

The word "decide" in this model only means that the model produced a particular visible next step. It does not mean a person can read the model's internal chain of reasoning, or that hidden reasoning is an accurate log of why something happened. Observable evidence can include messages, call arguments, tool results, timestamps, a diff or command output, but only those records that the specific product shows or stores.

A tool call: a request is not an execution

A tool description tells the model:

• the name that identifies the operation;
• the purpose, explaining when it is appropriate to choose it;
• the argument schema, meaning the expected fields, their types and which are required;
• sometimes a list of allowed values or further constraints.

A schema eliminates some formatting errors, but it does not replace checking business rules. Perfectly valid JSON (JavaScript Object Notation, a text format for exchanging structured data) can still contain the wrong project identifier or a dangerous value.

The full cycle of a call usually looks like this:

1. The harness passes the model the context and the schema of the available tool.
2. The model returns a structured tool name and arguments.
3. The client or server validates them, applies authorisation and decides whether confirmation is needed.
4. The runtime or the external service tries to perform the action.
5. The harness receives the result or the error and passes it back in the next request.
6. The model produces the next action or a text response.

For example, the model might ask a read_file tool to open src/billing.py. If the schema accepts a path field, that still does not mean the file exists, sits in an allowed directory or is accessible to this particular session. The real result might be the contents, an access error or "file not found".

In Claude's programmatic interface, a request for a client tool comes back as a tool_use block; the application executes the call and sends back a tool_result. In some services the vendor itself runs a server-side tool. In OpenAI's programmatic interface, a function call is usually one step of a dialogue between the model and the program: the application receives the call, runs its own code and returns the result with a reference to that same call. Some piece of code has to perform the action; the name of the API does not hide that.

These differences explain why a call with the same meaning can behave differently in Claude Code, ChatGPT, Codex, a standalone SDK and an application you built yourself. A product may have its own set of built-in tools, its own log and its own confirmation policy.

Message, action and evidence

Level	What you saw	What you can conclude from it
Message	"Changed the file", or a command written as text in the response.	The model reported an intention or claimed a result. This is not yet a record of execution.
Action request	write_file(path="…", contents="…") or create_issue(...).	Arguments for an operation were produced. Producing them does not prove the operation ran.
Execution record	The tool answered ok, returned exit code 0, or reported an error.	The tool reached some outcome. You still need to establish what ok means and whether the intended side effect happened.
Independently verified state	Re-reading the file, checking the created record in the service, a full test result on a known revision.	There is concrete evidence of a specific state, captured in a way that can be compared against the success criterion.

An empty response or a timeout does not prove the action failed either. The server may have written the record and the response got lost. For an action that changes external state, the safe order is: first check whether the result already exists, and only then decide whether to retry. A retry can create a duplicate, send two emails or charge a payment twice. If the operation supports an idempotency key (an identifier that lets the service recognise a repeat of the same request), that reduces the risk, but you need to check the documentation of that particular API.

A record of exit code: 0 means the process finished with a code the shell treats as success. On its own it does not prove the command ran the right tests, on the right branch, or covered every scenario. Evidence has to be matched against the request, the revision of the files, the scope of the check and the exact criterion.

Environment, access and permissions

The execution environment determines what a tool can use: which files are mounted, which directory the process starts in, which programs are installed, which environment variables are available, whether there is a network, how much time and memory are allotted. A sandbox can restrict reading and writing, network connections or access to other processes.

That is separate from whether a specific operation is allowed. For example, the code may sit in a mounted repository, but writing is blocked. The network may work, but there is no GitHub token. The token may exist, but be read-only. The tool may require confirmation before running. Different products combine these checks in different ways.

For an external system, you need to distinguish at least:

• whether the tool is present in the session;
• authentication (who exactly is making the request);
• authorisation (which operations this account is allowed to perform);
• whether the server is reachable over the network;
• the policy of the product or the workspace;
• confirmation of the specific side effect.

The model may have documentation for an API but no network route to it. A local program may have network access but no token. The token may be allowed to create an issue while the integration can only read. Approving one call may not mean standing permission for other calls. The exact rules have to be checked in the settings of the product and of the external system.

Permission is part of the runtime configuration, not a property of the model. A responsible boundary grants the minimum rights needed, shows read and write operations separately, and makes the consequences of a confirmation clear. Before an irreversible or sensitive action, establish the target, the scope and the consequence, and show the person a clear confirmation when policy requires it. After the action, verify the actual state.

Typical failures at different boundaries

Observation	Likely boundary of the problem	What to check next
The model invented a file, function or parameter name	The model's knowledge or incomplete context	Find the file in the repository and compare against the API contract.
The tool says "file does not exist"	Working directory, branch, path or access	Check pwd, the branch, the file listing and the allowed directories.
A command fails with an import error	Dependencies or the environment's interpreter	Compare versions, the lock file, the setup command and the installation log.
An API returns 401 or 403	Authentication or authorisation	Check the type of credentials and the permissions; do not ask the model to invent a missing token.
A write to a service timed out	Connectivity, or an unknown side effect	Read the current state first; do not blindly repeat the write.
A test passed in a narrow subset	The scope of the check, or a different state of the code	Check the full suite, the right revision and the other related scenarios.
The response says "done" but there is no log or diff	Observability, or a premature claim	Treat the status as unconfirmed and ask for evidence.

The text a tool returns can also be incomplete or wrong. For example, a web page in the repository might contain an instruction addressed to the agent. For the agent, that is content from a data source, not automatic permission to change the original requirements or send secrets anywhere. It matters to keep the distinction between input data, trusted instructions and authorisation for side effects.

Deterministic workflows versus agentic choice

A workflow is a process defined in advance: for example, receive a request, check the required fields, calculate the total, write the result. Every step has a predefined transition. If the input is the same and the system is deterministic, a repeat run usually reproduces the same path.

An agentic loop can use the model at each step to choose a tool or the next question based on new information. It is useful where you need to explore different files, choose between several ways of checking something, or ask for clarification. It is more flexible, but it does not give you repeatability for free: the same request can lead to a different order of steps, and the model can misread a signal.

Many real systems mix the two. Code checks the allowed transitions and the validity of arguments, while the model picks one of the allowed steps. Or an agent explores an unfamiliar project structure, after which an ordinary script runs with fixed acceptance gates.

If a task is fully defined, such as counting records every evening by the same rule, a plain, tested script may be simpler than an agent. A model is useful for ambiguous work, but handing it the choice does not fix an unclear requirement, does not replace access rules and does not prove correctness. Often the most reliable system gives the agent a bounded role around a verifiable sequence.

What state an agent sees and what it can keep

"The agent's state" is not one box of memory. You need to distinguish:

1. The context of the current request: system and developer instructions, the person's message, selected file contents and tool results.
2. Session history: earlier messages, calls and results, if the application stores them and adds them to the request.
3. Working directory state: files, uncommitted changes, the active branch, installed dependencies and running processes.
4. External state: Jira records, GitHub branches, database data, cloud jobs and their permissions.
5. Long-lived configuration or memory: separate instruction files, a profile, a saved task or a database, if the product supports and loads them.

The contents of the repository are not the same as the earlier conversation. Stored history does not mean that all its messages fit into the next request. If the context grows too large, the product may drop old results or compress them into a shorter summary. A compressed summary may keep the overall goal while losing the exact wording, the file version or an exception.

So moving to a new session should not be treated as automatically restoring every detail. To hand work over, it helps to have a compact, current description of the goal, the criteria, the changes made, the open questions, the branch or revision, and the verified evidence. Such a handoff does not replace re-reading the important files and the state of external systems.

How to tell agent products apart

The labels "chat", "coding agent", "SDK" and "managed agent" describe different parts of a system. One product may combine several of them, so the name alone does not always tell you who executes the code and what data it sees.

Type	What it usually provides	What you need to find out
Chat assistant	A conversational model; sometimes files or connected services.	Whether this session has access to the specific file or operation you need; an ordinary conversation does not open arbitrary local files or commands.
Coding agent	A loop with working files and tools to read, edit or run commands.	Where the runtime runs, which snapshot of the project it sees, which permissions and tools are enabled.
Model API and client SDK (software development kit)	Sending a request to the model and handling the response; the model may return a structured tool call.	Who implements and executes the client tool, where permissions are applied and how the result is returned. An SDK by itself does not open files or external services.
Agent framework	Libraries for the agent loop, step orchestration and tool calls.	Whether the loop runs in the developer's program, which components the framework runs itself, and what is left for the developer to configure.
Managed runtime	A service runs the agent loop and provides an environment for commands and files.	Where files and state are stored; where each tool runs (the application may run some of them); what rights the process has.

For any product, establish three things: where the action is executed, which resources and rights this particular session received, and which record proves the result. Elsewhere in this course, specific ecosystems are covered in detail, from CLAUDE.md, rules, skills, subagents, agent teams, hooks and MCP for Claude to AGENTS.md, OpenAI skills, Codex subagents and orchestration and plugins, MCP and skills. A product name or a model name is never by itself the answer to these three questions.

A historical snapshot of products, verified 23 September 2026

The map below is a historical snapshot of verified official descriptions as of 23 September 2026. It is not a current guide to availability or configuration, and not a complete catalogue of every plan, model, region, platform and setting. For a practical decision, check the current documentation for the vendor and account you need. Availability can depend on country, plan, client version, organisational policy, staged rollout and what an administrator has enabled. The presence of a product name in documentation does not mean it is available to every account. Vendors do not publish a single version number for the continuously updated software-as-a-service (SaaS) surfaces described here; where there is a separate version of a CLI, SDK or local client, it has to be checked for the specific installation. That is why the table gives the snapshot date, the statuses stated explicitly in the documentation, and the limits of the available version data, rather than invented version numbers.

Ecosystem	What the name refers to	Where the loop runs and what you should not assume
Claude (chat)	Anthropic's conversational product on the web, desktop and mobile. Depending on settings, it can use connected services.	Being a chat does not mean it works with a local repository or runs arbitrary shell commands. Once connected, a connector works only within its access, its settings and the operations allowed for it.
Claude Code	An agentic programming tool in the command line, an editor, a desktop application or a supported web environment.	Even though the model and the loop may be similar, where the code runs, access to the working directory, the network and the available tools all differ. The documentation describes local, cloud and separate remote modes; their parameters must be checked individually.
Anthropic API and Client SDK	An API for sending messages to the model programmatically; the Client SDK (software development kit) simplifies calls, types, data transfer, error handling and retries.	The SDK calls the API; it does not arbitrarily open files or Jira. With your own client tools, your application describes the schema, performs the operation, applies permissions and returns the result. Tools executed on the vendor's servers are a separate type.
Claude Agent SDK	A programming library that, according to current documentation, reuses parts of the Claude Code agent: its loop, its context handling and its built-in tools.	The developer runs it inside their own process and defines access, tools and the environment. It is not the same thing as the basic Client SDK for individual API requests.
Claude Managed Agents	Anthropic-managed infrastructure for long-running agent sessions, with an API for configurations, environments and session state.	As of the verification date, the documentation marks the agents and sessions API as beta; availability and support for environments cannot be assumed to carry over to other Anthropic plans or products.
ChatGPT Chat and Work	Chat is the general conversational interface. Work is a separate ChatGPT mode for more complex multi-step tasks that may run longer and interact with permitted apps and files.	The ChatGPT Help Center describes Work as a view separate from Chat and Codex. Local folders require desktop mode and explicit access; cloud sessions may reach files differently. Rollout and permissions vary between accounts.
Codex CLI (command-line interface), desktop application and editor integrations	OpenAI products for programming tasks: the command line and client integrations. As of 23 September 2026, Codex is a separate mode in the ChatGPT desktop application; on 9 July OpenAI announced that the Codex app was being merged into the new ChatGPT desktop app.	Computation can happen on the local machine or in a managed cloud runtime, depending on the scenario. In OpenAI's description, the App Server serves several client surfaces, but their specific set and capabilities are not identical. The desktop client version number and the CLI version must be checked in the specific installation; for the cloud surface, the verified sources give a date and feature descriptions but no single published version number.
OpenAI API and SDK	The Responses API lets you send requests to the model; tool calls are handed to the program's handler. The Agents SDK adds a loop, tools, handoffs and other mechanisms for building an agent.	Choosing between the Responses API, the Agents SDK and the Agents API determines who orchestrates the loop, where state is stored and who runs the tool. A client SDK does not automatically grant access to a computer or an external service.
OpenAI Agents API	As of the verification date, a public beta API with a managed Codex harness for long-running cloud agents.	The documentation describes managed sessions and an optional environment: an OpenAI-hosted sandbox, a self-hosted sandbox, or no sandbox. The beta and its limits do not mean the environment is the same as for Codex CLI, ChatGPT or the Agents SDK.

OpenAI's public post of 4 February 2026 describes the Codex App Server and the ways various clients use it, including local applications and editor integrations, the Codex Web runtime and the command line. A later ChatGPT Work and Codex help page, verified on 23 September 2026, describes Codex as a separate mode in the ChatGPT desktop application and says it cannot be selected in web or mobile ChatGPT, although supported remote sessions can be opened on a mobile device. OpenAI's announcement of 9 July 2026 states that the Codex app is being merged into the new ChatGPT desktop app. So the mention of a "Web runtime" in the February architecture post is no guarantee that every account has access to the same web page, or that it is part of ChatGPT on the web.

Claude Code and Codex are not "just the model". They include a harness and conventions for managing context and tools. The Anthropic Client SDK and the OpenAI API client are a program's path to the model API; an agent library adds the loop; a managed Agents API can add a hosted harness and an environment. The names are similar, but their areas of responsibility differ.

Product availability changes. The table records what official documentation and publications said on the review date. It does not replace the current documentation for a specific account or organisation. It is especially important to check which surface actually executes the code, which network restrictions are in place, and which access credential the integration uses.

Example 1: a failing test, and a second problem after the first fix

The setup

Imagine a fictional shop with a discount function. The authoritative rule in this teaching example says: amounts are stored in whole cents and cannot be negative; the discount is a whole number from 0 to 100 percent; the remainder is rounded to the cent using "round half up". The file src/pricing/discount.py, the functions and the results below are invented. This is not a real task and not an actual test run.

The first visible record from continuous integration (CI, the automated integration check) shows one failing test:

FAILED tests/test_discount.py::test_half_up_rounds_up
Expected: 905
Actual:   904

This line shows a concrete mismatch, but it does not yet explain the cause. The model could guess straight away that some rounding somewhere does not follow the rule. Instead, the agent starts with verifiable steps:

Step	Visible action	Actual result in this fictional example
1. Observe	Read the criterion and the CI record.	It is unknown whether CI tested exactly the current local revision; that still needs to be matched.
2. Investigate	Read src/pricing/discount.py and the test test_half_up_rounds_up.	The function contains round(amount_cents * (100 - percent) / 100). The test expects 905 for 1005 cents with a 10% discount.
3. Decide	Return a short, testable hypothesis: the rounding used turns 904.5 into an integer by a rule other than the agreed "round half up".	The hypothesis is consistent with the concrete input; the model's hidden reasoning is not needed to check it.
4. Act	Change the formula to add 50 before integer division by 100 for non-negative valid values.	The visible diff shows the code change. The diff alone does not prove the test passes.
5. Inspect	Run the targeted test: pytest -q tests/test_discount.py::test_half_up_rounds_up.	Fictional output: 1 passed. The specific failure is fixed for this scenario.
6. Widen the check	Run all the module's tests: pytest -q tests/test_discount.py.	The fictional output reveals another scenario, test_negative_percent_rejected: the function did not reject a discount of -10.

The second result does not contradict the first. The targeted test checked the rounding rule; the full test file added a different condition, the boundary of valid values. After the first change, the agent has no right to declare the whole task done just because one specific example turned green.

Next the agent opens the failing test and the criterion. The condition 0 ≤ percent ≤ 100 is stated clearly in the fictional rule, so what is needed is a boundary check, not a new product guess. The function gets checks for a negative amount and for a percentage outside the range. After the second change, the agent runs the whole module suite again.

In this fictional scenario the final log says 9 passed; the diff and the output show the same revision, and a search of changes confirms that unrelated files were not touched. That is sufficient evidence for the narrow criterion "this module's tests passed on the revision shown". It does not prove the whole application is ready to release: that requires other checks and agreed criteria.

This loop makes visible the difference between five things: the initial error report, the hypothesis, the recorded change, the actual command output, and an independent assessment of the full scope of the check. The answer "fixed" only becomes stronger when the corresponding evidence backs it up.

Example 2: knowing about Jira without a Jira tool

The setup

Imagine a fictional chat with no Jira connector, no token and no other write operation. A person asks: "Create a Jira issue about the double charge, assign it to the support team and tell me the issue number." The data in this example is invented.

The model may know Jira's usual fields: summary, description, project, priority, assignee. That is not enough to create a record. The tools available in the current chat include nothing like create_issue, so the loop cannot move from text to an action in Jira.

An honest reply might be:

I don't have a Jira tool connected in this session, so no issue has been created and there is no issue number. I can prepare a draft: Summary: Investigate report of a duplicate charge. Description: Reconcile the charge logs for the transaction ID provided and confirm whether there is a duplicate. Project, assignee and priority: need to be chosen in the available workspace.

This is a message and a draft, not a created issue. It has no Jira identifier, no API response and no entry in the project history. For the claim "the issue was created" to be justified, the application must provide the right integration tool, the authenticated account must have permission to create issues in that specific project, and after the call the result must come back and, for an important action, the record must be checked in Jira itself.

Even once the integration is connected and the tool returns an error, the agent must tell the cases apart: "tool unavailable", "re-authentication required", "not permitted to create", "project not found" and "request timed out" are different facts. In the case of a timeout, the record may already exist, so before retrying it is worth searching for it by its known fields or by the idempotency key.

Example 3: the same command locally and in the cloud

The setup

Imagine a fictional repository where the command python -m pytest -q finishes locally with 12 passed, but in a cloud sandbox returns ModuleNotFoundError: No module named 'dateutil'. All names, commands and results in this example are invented.

The command is textually identical, but the environment is different. The laptop may still have a globally installed library that the versioned code does not declare. In the cloud, the dependency never made it into the lock file, or the package installation step did not run. At this point it is unknown which of these causes is the real one.

The agent should not immediately change the application code or announce that the model is performing worse. It checks the visible facts: which Python and which directory were used, which manifest and lock file declare the dependency, and what the cloud job's setup log recorded. If the dependency really is missing from the configuration, the team decides where to declare it; then the environment is rebuilt from scratch and the same test suite is run again.

In this fictional scenario, the team adds the confirmed dependency to the project file, creates a fresh cloud environment and gets 12 passed. The evidence here is not that the last message looks like the local result, but the installation log, the actual interpreter and dependency versions, the revision identifier and the repeated test result.

A local run may see files, secrets, databases and network resources that the work computer has access to. A cloud run may see only the snapshot of the repository it was given and separately issued resources; its dependencies, network policy and retention period may differ. Some products synchronise state between the local client and the cloud; others keep sessions separate. So in any case you have to establish where exactly the action runs and which data and permissions were passed to it.

Failures, verification and responsibility

Common failures in agent work form a chain, and every link needs evidence:

• A false fact or file. The model names a method or a path that does not exist. Check: search the source that is authoritative for this specific repository.
• Incomplete observation. The agent reads one file but misses a caller, a configuration or a neighbouring test. Check: search for references, dependencies and contracts.
• Misinterpretation. Command output is read as success although it was truncated or an error was missed. Check: the full result, the exit code and the process identifier.
• The wrong tool. A write is performed instead of a read, or the tool runs in a different directory. Check: the name, the arguments and the conditions of that specific call.
• An unconfirmed side effect. An external action may have gone through even though the client got no response. Check the state before retrying.
• Premature completion. The agent passed one test but not the full criterion, or produced a success message without any tool result. Check: the match between the requirement and the actual scope of the evidence.
• Changes after verification. Files changed after the green run. Check: pin the revision and repeat the relevant checks.

Open user reports in the Codex repository illustrate why the harness matters: one author described long commands being interrupted and output being truncated during a test run. This is a single user report in a GitHub issue, not a measurement of how common the problem is and not a guarantee about the current behaviour of every version. It simply shows that a failure can occur at the tool boundary, before the model ever receives the result it needs.

Human responsibility does not disappear when work is handed to an agent. A person or a team defines the acceptable boundaries, resolves product ambiguity, reviews the changed files, assesses side effects and decides whether the evidence is sufficient for the next step. An agent can propose code or go through part of the loop; its confidence, how long it worked and how many calls it made are not measures of correctness.

For an important change, it helps to keep a short log: the goal, the revision, the tools, the actual results, the unverified assumptions, the external records that may have changed, and what remained outside the scope of verification. An independent reading of the diff or a repeat check of the result helps catch misinterpretation. Where the cost of an error is defined by business decisions, security, data or commitments to a client, a responsible decision by an authorised person is required.

Summary

An AI coding agent is a model inside an application that adds instructions, context, tools and execution rules. The model can propose an action; a specific client-side or server-side tool executes it, in a specific runtime, with specific permissions. Local environments, cloud environments and those connected to external services all have different boundaries.

A meaningful loop runs from observation to checking the result, and repeats as needed. A structured call is not an execution; a success message does not replace a log, a diff, the actual state of a service or a check on the right revision. Context can be limited or summarised, and product surfaces and available permissions change. So it pays to set narrow criteria, leave observable evidence, and never draw stronger conclusions than that evidence supports.

Context as a limited resource examines context in more detail, and the instruction hierarchy covers instructions. The units on specific ecosystems listed above show how to work with each of them. In every individual task, check again what exactly is the model, what the harness provides, where the tool runs, and which visible result confirms the action.

Sources and further reading

The product pages and documentation supporting the examples below were checked on 23–26 September 2026; the pages on tool use and function calling were reopened on 10 October 2026. Links to live documentation without a visible publication date may change. A vendor's public report describes its own system and stated architecture; it is not an independent assessment of reliability. This unit contains no independent benchmark or comparative testing of products. The teaching examples and their outputs are synthetic.

1. Anthropic, Claude Code Overview, current documentation with no visible update date; checked 23 September 2026. Supports the description of Claude Code and its stated surfaces: the command line, the integrated development environment (IDE), the desktop application and the web. This is the vendor's description, not a check of availability for every account.
2. Anthropic, How Claude Code works, current documentation with no visible update date; checked 23 September 2026. Supports the description of the agent loop and the roles of the model, tools, environments and sessions.
3. Anthropic, Configure permissions, current documentation with no visible update date; checked 23 September 2026. Supports the claim that permissions depend on tool and environment policies. The configuration examples describe that product's implementation, not a general rule for all agents.
4. Anthropic, Tool use with Claude, current documentation with no visible update date; checked 10 October 2026. Distinguishes client tools, where the application executes the request and returns a tool_result, from server tools, which Anthropic executes.
5. Anthropic, Claude API overview, current documentation with no visible update date; checked 23 September 2026. Supports the description of the Messages API, the Client SDK and the separate beta stage of the API for managed agent configurations and sessions. This status may change.
6. Anthropic, CLI, SDKs, and libraries, current documentation with no visible update date; checked 23 September 2026. Distinguishes the official command line, the API client libraries and integrations with other frameworks.
7. Anthropic, Agent SDK overview, current documentation with no visible update date; checked 23 September 2026. Supports the distinction between Claude Code as a CLI, the Agent SDK, the Client SDK and Managed Agents by where and by whom the loop is run.
8. Anthropic Engineering, Scaling Managed Agents: Decoupling the brain from the hands, published 8 April 2026; reviewed 23 September 2026. Anthropic's own account of its managed agents and of how harness assumptions change over time; not independent research.
9. Anthropic Help Center, Use connectors to extend Claude's capabilities, published 20 August 2026; reviewed 23 September 2026. Supports the point that connectors are limited by the rights in the source service, the access settings and the permitted category of actions.
10. OpenAI, Unlocking the Codex harness: how we built the App Server, engineering article of 4 February 2026; reviewed 23 September 2026. Supports the description of the App Server, the visible elements of a session, permission requests and the different client surfaces. This is OpenAI's description of its own system.
11. OpenAI, Introducing the Agents API, announcement of 10 September 2026; reviewed 23 September 2026. Labels the Agents API as a public beta and describes its use of the managed Codex harness; availability and actual limits depend on the API configuration.
12. OpenAI, Agents API overview, current documentation; checked 23 September 2026. Supports the distinction between the agent, the environment, the session and events, as well as managed context and the possible environment types.
13. OpenAI, Agents, current documentation; checked 23 September 2026. Compares the Agents API, the Agents SDK and the Responses API by where the loop runs, state, tools and environment.
14. OpenAI, Function calling, current documentation; checked 10 October 2026. Describes five steps: pass the available tools, receive a call, run the code on the application side, return the result, and receive the final answer or the next call.
15. OpenAI, ChatGPT Work and Codex, help page checked 23 September 2026; at the time of viewing, the page showed a relative indicator, "updated 19 hours ago", rather than a stable revision date. Describes Chat, Work and Codex as different surfaces; notes that access, the file environment and synchronisation differ. The content changes quickly.
16. OpenAI, ChatGPT is now a partner for your most ambitious work, announcement of ChatGPT Work of 9 July 2026; reviewed 23 September 2026. This is the vendor's claim about multi-step tasks and integrations, not an independent assessment of how often such tasks are completed or how accurate they are.
17. OpenAI, Codex CLI repository, OpenAI's official open-source repository; reviewed 23 September 2026. Confirms that Codex CLI is a software project for the command line and that the repository contains its implementation and tools. The state of the branch may change.
18. A GitHub contributor, OpenAI Codex issue #6721: Harness interrupting shell execution and/or truncating output, opened 16 November 2025; closed as of the review date. A single user report concerning version 0.58.0, in that user's own words; it is not an independently reproduced measurement, a response from OpenAI or evidence of current behaviour.
19. Anthropic, Tools for Claude Managed Agents, current documentation; checked 26 September 2026. Distinguishes the built-in tools of a managed agent from custom tools that the application executes.

Limits of the sources. The information about Claude and OpenAI comes from documentation, help pages and statements by the vendors themselves. It helps distinguish the stated components, APIs and environment types, but it does not prove that a specific action is available in every account or will complete successfully. The OpenAI GitHub issue cited is primary evidence that one user described a specific failure; its closed status without a response and the absence of independent reproduction do not allow generalising about how often the problem occurs or whether it still exists.

The labels chat, coding agent, SDK, agent framework and managed runtime do not always map onto separate products: one system can combine several types. Before starting work, check the current documentation for the exact surface, installation and account you need. This unit deliberately gives no model versions, prices, limits or availability promises, because they go stale quickly.

Historical uncertainties recorded as of 23 September 2026. The OpenAI Codex documentation address mentioned in the original research (https://developers.openai.com/codex/) redirected at the time to the general ChatGPT Learn section; Codex surfaces were therefore checked against OpenAI's engineering article, the official repository, a separate help page and the API documentation. The App Server article named a Codex Web runtime, while the ChatGPT help page said Codex cannot be selected in web or mobile ChatGPT. These records described different surfaces and did not confirm equal availability for all accounts. At the same time, the Anthropic API overview marked the Agents, Sessions and Environments APIs for Managed Agents as beta features. This is a historical note; check current availability against the current documentation.