Practical Guide to Controllability in Long AI Coding Agent Sessions

1. Problem Definition: The Real Bottleneck Is Not the Model, but the Engineering Shell

A common situation is that coding agents usually operate in a stateless mode by default: once the session ends, the context is lost; switching to a new terminal is like onboarding from scratch again. In practice, the four most common bottlenecks are rarely caused by insufficient model capability:

1. One-time context: every new session requires re-explaining the project structure, build commands, and code conventions. This repeated cost is often seriously underestimated.
2. Context bloat: during long tasks, raw file contents and raw command outputs keep accumulating. The effective context budget is squeezed by noise, attention is diluted, and the agent may appear “lost in the middle.”
3. Autonomy mismatch: either every edit requires confirmation, fragmenting interaction, or all permissions are open, making it hard to roll back after a mistaken operation damages multiple files.
4. Non-reusable experience: the constraints, commands, and review standards tuned by experienced engineers remain stuck on individual terminals and cannot be delivered to the team.

The conclusion is clear: the gap between “getting it running” and “controllable and reusable” lies in four types of shell engineering: session management, context engineering, permission governance, and task orchestration, not in swapping in a stronger model.

2. A Five-Layer Capability Model: Build a Troubleshooting Coordinate System

To use these tools deeply, the first step is to establish a layered coordinate system for agent capabilities. The architecture of coding agents can generally be broken down into five layers, which also serve as the order for troubleshooting:

Layer	Problem It Solves	Key Mechanisms	Typical Failure Symptoms
L1 Tools and Execution	What the agent can do	Tool registration, dispatch patterns, parameter schema validation	Repeatedly calling nonexistent commands, malformed parameters, silent execution failures
L2 Planning and Control	How work is organized	Task lists, sub-agent delegation, on-demand loading of skills/rules	Forgetting the goal midway through long tasks, skipping steps, duplicated work
L3 Memory Management	Maintaining memory within a limited window	Layered compression pipeline, externalized memory, retrieval-based backfill	Rework after compression, lost constraints, inconsistent solutions
L4 Concurrency and Scheduling	Background execution and scheduled triggering	Background tasks, scheduled jobs, idempotent retries	Write conflicts, stuck tasks, inability to consolidate results
L5 Multi-Agent Collaboration	Division of labor across multiple agents	Message passing, workspace isolation, standard tool protocol integration	Conclusions overwriting each other, context contamination, coordination cost exceeding benefits

The value of a layered model is fault attribution. If the agent “forgets what I said earlier,” first check whether the issue is L3. If it “modifies unrelated test files,” that usually points to isolation gaps in L1 or L5. If it “changes direction halfway through execution,” that is often an L2 goal-anchoring problem. Without layers, teams can only rely on retries and luck.

3. Session Persistence: Keep Work State Alive Across Terminals and Time

From an engineering perspective, sessions should be treated as archivable work units, not one-off conversations.

Session identifiers and persistence. Assign a stable identifier to each session and persist session records, task lists, and intermediate conclusions to a fixed directory inside the project, for example .agent/sessions/<date>-<topic>/. The test is simple: if you switch machines or reopen the project a day later, can you continue without restating the background?

Handoff documents are better than one long session. Long sessions are themselves a risk source. A recommended practice is to produce a structured handoff document for each stage of a task:

# Handoff: Idempotent Payment Callback Refactor
## Goals and Acceptance
- Goal: Make callback processing idempotent so duplicate deliveries do not create duplicate ledger entries.
- Acceptance: Concurrent replay tests produce zero duplicate ledger entries 100% of the time.
## Decisions and Rationale
- Use a unique index plus a state machine instead of a distributed lock. The lock granularity is too coarse and does not meet throughput requirements.
## Key Locations
- src/payment/callback.go:88 (handler)
- src/payment/ledger.go:210 (ledger entry)
## Incomplete Items
- [ ] Compensation task not integrated
- [ ] Load testing not run
## Forbidden Actions
- Do not modify existing files under db/migrations

The value of this document is that it works as a common middleware across sessions, people, and tools: it can be used as the first context entry for a new session, and also as fallback memory after compression.

Checkpoints and branches. For tasks that modify many files, use version control to create rollback-friendly checkpoints. For solution exploration, use parallel session branches to validate two designs separately, then merge the chosen one. This avoids contaminating the main thread with experiments.

4. Commandization: Turn Repeated Prompts into Versionable Assets

The next step for individual efficiency is to distill high-frequency prompts from “chat history” into reviewable, version-controlled instruction files inside the project.

Layered placement rules avoid injecting all constraints unconditionally:

• User level: cross-project preferences, such as commit message style, comment language, and answer verbosity.
• Project level: technology stack, build/test/lint commands, directory responsibilities, and forbidden paths.
• On-demand level (skills/subcommands): loaded only in specific scenarios, such as code review, migration, or performance profiling. These contents are usually large, and always-on injection significantly increases cost and noise.

Template instructions and replace free-form descriptions with placeholders:

---
name: review-diff
description: Perform a structured review of the current changes
params: [scope, severity_threshold]
---
Review only changes within {scope}. Ignore formatting differences.
Produce output in the following order. Each item must include file:line:
1. Correctness issues (edge cases, concurrency, exception paths)
2. Security issues (input validation, authorization, secret exposure)
3. Performance issues (complexity, N+1 queries, unbounded memory)
4. Maintainability
Report only issues with severity >= {severity_threshold}. If a category has no issues, write "None".
Do not modify code directly. Output review conclusions only.

Three design principles:

• Fixed output structure: easier to compare and consume automatically.
• Explicit prohibitions: narrows the behavior space.
• Parameterizable scope: one template can cover multiple scenarios.

Combined orchestration. Encode stable workflows as fixed pipelines instead of describing them verbally each time:

# Example: local one-stop development loop
agent run --mode plan   --input task.md          # Produce a plan first; do not modify code
agent run --mode edit   --input plan.md          # Implement according to the plan
agent run --command "test ./... && lint"         # Verify
agent run --input handoff.md --mode review       # Self-check and review

5. Permissions and Boundaries: Tiered, Not One-Size-Fits-All

Autonomy must be matched to risk. An effective practice is to define five levels and allow dynamic switching during a session:

1. Read-only planning: read and retrieve only, produce a plan, and make no writes.
2. Edits require confirmation: files may be edited, but each write requires human approval.
3. Auto-accept edits: in-scope files are written automatically, but command execution still requires confirmation.
4. Autonomous within a sandbox: operate freely inside a container or temporary directory, with restricted network access and host path access.
5. Full bypass: use only for one-off, disposable, isolated environments. Do not use it in environments containing real data or production credentials.

A supporting risk matrix should define actions that require human approval in any mode: production writes and data deletion, database migrations, releases and rollbacks, global package installation, reading secret or credential files, and sending external network requests.

Three hard engineering constraints are also needed:

• Least privilege: tool authorization scope is trimmed according to the task.
• Default read-only: capabilities are not enabled unless explicitly authorized.
• Auditable: all tool calls and command executions leave records.

For enterprise adoption, runtime traces can be unified into logging services, monitoring alerts, and object-storage archive pipelines, for example by using general-purpose capabilities such as those offered by Baidu AI Cloud. This makes “who asked the agent to change what, and when” traceable, measurable, and alertable.

6. The Context Compression Pipeline: The Core Factor in Long-Task Success

This layer is easy to overlook, but it has the highest payoff. With a limited context window, costs growing over time, and attention decay in long contexts, compression is not an optimization; it is a requirement.

Four-layer progressive compression, triggered from light to heavy as needed:

1. Trimming layer: remove stale tool outputs and repeated file reads beyond the budget, while keeping the most recent few turns.
2. Summarization layer: summarize groups of exploration steps, keeping conclusions and key intermediate artifacts.
3. Structured extraction layer: distill the conversation into machine-readable “task memory” and replace the raw conversation.
4. External retrieval backfill: move full content out of the window, persist it to files, and retrieve it by keyword or path when needed.

Six types of information must be preserved during compression. This is key to preventing behavior drift after compression:

• Goals and acceptance criteria
• Decisions made and their rationale
• Key file paths and symbol locations
• List of incomplete items
• Explicit constraints and prohibitions
• Records of failed attempts, to avoid repeating the same mistakes

What can be downsampled or discarded:

• Full file contents: keep the path and summary only.
• Raw command output: keep the exit code and error summary.
• Intermediate reasoning from exploratory trial and error.

Post-compression self-checks cannot be skipped. Ask the agent to restate the goal, acceptance criteria, and forbidden actions, then compare them line by line with the handoff document before continuing. Skipping this step is the main cause of “rework after compression.”

Example of structured task memory:

goal: Make payment callbacks idempotent
acceptance: 100 concurrent replays produce zero duplicate ledger entries
decisions:
  - {choice: Unique index plus state machine, reason: Distributed lock granularity was too coarse and throughput was insufficient}
files:
  - {path: src/payment/callback.go, note: Idempotency check entry point, line: 88}
todo: [Integrate compensation task, Run load testing]
forbidden: [Modify existing migration files, Introduce new middleware]
failed_attempts: [Redis-based distributed lock; load-testing QPS dropped by 40%]

7. Sub-Agents and Concurrency Scheduling: Calculate Coordination Cost First

There is only one split criterion: whether the benefit of context isolation is greater than the cost of coordination and merging. Scenarios suitable for splitting usually have three features: clear input boundaries, outputs that can be compressed into conclusions, and low write conflicts between tasks. Examples include broad code retrieval, cross-module impact analysis, parallel validation of multiple candidate implementations, and independent security review.

The protocol should be agreed as “return conclusions only”. Subtasks should return structured results, such as conclusions, evidence locations, and unresolved items, rather than pushing all intermediate processes back into the main context. Otherwise, the isolation is wasted.

Concurrent writes must be isolated. If multiple agents share the same workspace, files may overwrite each other and build artifacts may be polluted. The common practice is to use an independent workspace copy or an independent version-control branch for each concurrent task, then perform integration validation during the merge stage.

Background and scheduled tasks are suitable for long-running and periodic work. Move long builds and full test suites to background execution. Delegate dependency-upgrade checks, nightly regressions, and stale-document checks to scheduled jobs. All such tasks must be idempotent and retryable: repeated execution should not produce side effects, and after failure they should resume from a checkpoint instead of starting over.

8. Measurement: Turn “Familiarity” into Something Provable

To answer “Are we using this well?” with data, track at least these metrics:

• Task first-pass rate: the proportion of tasks that meet acceptance criteria without human rework.
• Human interventions per task: a direct measure of interaction friction.
• Compression trigger count and post-compression rework rate: whether L3 memory management is healthy.
• Invalid token ratio: the ratio between always-injected content and actually relevant content. This is the basis for trimming rule files.
• Blocked dangerous operations: whether permission policies are actually working.
• Average recovery time: the time needed to resume existing progress from a new session. This tests the persistence design.

Two supporting practices are also needed:

• Build a regression test set: 10 to 30 fixed inputs covering common task types, used to verify that changes to rule files and instruction templates do not introduce regressions.
• Version rules and templates and roll them out gradually: first run a regression pass in a personal environment, then distribute to the whole team.

9. Common Anti-Patterns

• Piling all work into one extremely long session until compression eats key constraints.
• Treating full autonomy as the default instead of enabling it temporarily based on task risk.
• Letting rule files grow without limits and injecting them all at once, which increases both cost and noise.
• Giving the agent goals but no prohibitions, leaving the behavior space uncontrolled.
• Letting concurrent tasks share the same workspace, causing results to pollute each other.
• Allowing credentials and secrets to enter the conversation context and be persisted with session records.
• Focusing only on generation quality and not recording runtime traces, making issues impossible to attribute.

10. Recommended Rollout Path

Phase 1 (about 2 weeks): unify build, test, and lint commands as well as rule files for the project; establish session persistence and handoff document templates.

Phase 2 (about 1 month): implement permission tiers and the risk matrix, connect runtime logs and alerts, and establish a regression test set.

Phase 3 (about 2 months): commandize high-frequency workflows into fixed pipelines; introduce post-compression self-checks.

Phase 4 (about 1 quarter): introduce sub-agents and workspace isolation in scenarios with clear benefits, integrate external system capabilities, and drive rule iteration with metrics.

What really creates differentiation is not who uses the newest model, but who treats sessions, context, permissions, and orchestration as engineering objects: persistable, versionable, auditable, and measurable. Once these four points are in place, the stability of long tasks and the repeatability of team collaboration can grow along with model capability.