Coding Agent

Problem

A coding agent combines untrusted repository content, probabilistic planning, command execution, package managers, network access, and write operations. Treating it as a text generator ignores the material risk created by shell commands, secrets, dependency installation, generated code, and changes to protected branches. The system must distinguish inspection, reversible workspace changes, external communication, credentialed operations, and irreversible administrative actions.

Why a runtime layer is needed

The application runtime turns a coding request into a bounded execution session. It owns repository identity, branch and path permissions, sandbox configuration, tool classes, secret references, approval gates, budgets, idempotency, diffs, tests, and evidence. The model may propose commands, but the runtime decides whether a command is representable, permitted, isolated, observable, and eligible for execution.

Reference architecture

A session broker validates repository, revision, actor, task scope, deadline, network policy, and approval requirements.
A short-lived sandbox mounts a clean working copy with explicit writable paths and resource limits. Host credentials and developer home directories are not inherited.
Repository tools expose structured read, search, edit, diff, and status operations; a command tool accepts an argument vector and working directory instead of an unparsed shell string wherever practical.
A policy engine classifies operations as read-only, reversible write, external communication, privileged administration, or destructive action.
Secrets are supplied by reference to narrowly scoped tools and are never inserted into prompts, command output, diffs, or trace attributes.
Tests and static analysis run in a reproducible environment. The runtime captures exit status, bounded logs, changed files, generated artifacts, and dependency deltas.
A human reviews the diff and evidence before merge, deployment, credential use, external communication, or other high-impact transitions.

Request flow

Resolve actor, repository, base revision, allowed paths, task type, and risk level.
Create an isolated workspace and verify the checked-out commit hash.
Read repository guidance and gather only task-relevant context.
Generate a plan and classify each proposed tool action before execution.
Execute allowed reads and reversible writes; pause for approvals required by policy.
Run tests, linters, and security checks under the same bounded environment.
Produce a diff, test summary, unresolved risks, and evidence record; never merge or deploy unless explicitly authorized.

Contracts

Runtime request: repository URL or stable identifier, base commit, task, path allowlist, network policy, risk level, budget, deadline, and approval policy.
Command tool: executable allowlist, argument schema, working-directory policy, environment-variable allowlist, timeout, output cap, network class, and side-effect class.
File-edit tool: allowed roots, expected preimage hash, patch format, maximum changed bytes, and conflict behavior.
Approval contract: action digest, diff or command preview, approver authority, expiration, single-use semantics, and recorded decision reason.

Failure modes and recovery

Detection, behavior, retry, idempotency, recovery, and evidence
Failure	Detection	User-visible behavior	Retry and idempotency	Recovery and evidence
Repository revision drift	Workspace HEAD no longer matches the admitted base commit.	Stop and ask for rebase or explicit re-admission.	Do not retry writes against a changed base. Every patch carries an expected preimage or base commit.	Discard or preserve the isolated workspace for review; create a new session for the new revision. Evidence: Admitted commit, observed commit, changed files, and stop reason.
Command denied	Policy rejects executable, arguments, path, network class, or privilege request.	Show the denied operation and a policy-safe alternative when available.	Retry only with a materially different permitted action or explicit approval. No command process is started for a denied action.	Escalate privileged needs to a human-owned workflow. Evidence: Normalized command, decision, policy version, and reason codes.
Test timeout or resource exhaustion	Sandbox deadline, CPU, memory, process, or log limit exceeded.	Return partial test results and identify the limit reached.	Eligible only after scope reduction or an approved budget increase. Test runs have unique attempt IDs and do not mutate external systems.	Terminate process tree, preserve bounded artifacts, and mark results incomplete. Evidence: Limits, consumed resources, process status, and retained logs.
Secret exposure detected	Secret scanner identifies a credential pattern in prompt context, output, diff, or logs.	Suppress the value, stop affected external operations, and require incident handling.	Do not regenerate with the secret present. Rotate or revoke exposed credentials before further execution.	Redact retained artifacts and follow the organization’s incident process. Evidence: Secret reference, detection location, redaction action, and rotation status—never the secret value.
Partial external side effect	Package publication, issue creation, comment, or remote API call returns ambiguous completion.	Report uncertainty and do not repeat automatically.	Retry only after reconciling using a provider idempotency key or authoritative status check. External writes require deterministic idempotency keys where supported.	Query the target system, compensate when supported, and require review when state is ambiguous. Evidence: Request key, provider response identifiers, reconciliation result, and compensation.

Security considerations

Treat repository files, issues, test fixtures, and build output as untrusted inputs capable of prompt injection.
Use ephemeral, non-root sandboxes with process, filesystem, network, CPU, memory, and time limits.
Deny ambient credentials. Bind narrowly scoped, short-lived credentials to specific approved tool operations.
Require review for protected-path changes, dependency provenance changes, security-control edits, external communication, and deployment actions.
Normalize paths and command arguments; reject traversal, unsafe symlinks, unexpected interpreters, and shell metacharacter expansion where structured execution is available.
Redact logs and diffs before persistence, while retaining enough evidence to reproduce the decision and execution path.

Observability

Trace model calls, plan revisions, tool decisions, command starts/stops, file hashes, test suites, approvals, and external API calls under one correlation ID.
Capture resource consumption, process exits, changed-file counts, diff size, test outcomes, denied actions, and approval latency.
Keep full command output in bounded artifacts with access controls rather than oversized telemetry attributes.
Alert on repeated policy denials, unexpected network destinations, secret detections, protected-path attempts, and ambiguous side effects.

Evaluation

Measure task correctness using repository-specific tests and human diff review, not model self-assessment.
Evaluate security behavior with malicious repository instructions, dependency-confusion scenarios, secret bait, symlink attacks, and deceptive test output.
Track whether the agent identifies missing requirements, stops at approval boundaries, and reports incomplete verification.
Replay fixed tasks across model, prompt, sandbox, and tool-policy versions before promotion.

Metrics

Accepted-change rate after human review
Test pass rate and regression escape rate
Policy-denial rate by action class
Protected-path and secret-exposure incidents
Time to first useful diff and total review time
Command, token, compute, and artifact-storage cost per accepted task
Rollback or rework rate after merge

Implementation checklist

Define repository, path, branch, command, network, and secret boundaries.
Use immutable base revisions and expected-preimage hashes for edits.
Run in ephemeral sandboxes with no inherited developer credentials.
Classify every tool by side effect, privilege, egress, and approval requirements.
Require deterministic evidence for changed files, commands, tests, approvals, and external effects.
Test adversarial repository content and ambiguous external-write recovery.

Sources

OWASP Top 10 for Agentic Applications 2026

OWASP Foundation · Security guidance · 2026-06-23T00:00:00Z

Threat-model guidance for autonomous planning, tool use, memory, identity, and multi-agent interactions.
OWASP Top 10 for LLM Applications 2025

OWASP Foundation · Security guidance · 2026-06-23T00:00:00Z

Threat categories for prompt injection, sensitive information disclosure, excessive agency, and insecure output handling.
Security in GitHub Codespaces

GitHub · Official product documentation · 2026-06-23T00:00:00Z

Concrete isolation and credential-handling considerations for remote development environments.
OpenTelemetry Traces

OpenTelemetry · Official project documentation · 2026-06-23T00:00:00Z

Trace and span semantics used to correlate runtime, model, tool, and policy operations.

Find runtime definitions and implementation guidance