Agent Loop

Agent Loop

Use agent-loop to turn a local source into a resumable execution loop with explicit plan state, explicit evidence, and explicit stop gates.

Default to the pragmatic file-backed profile. Use the higher-rigor packet and runtime references only when the environment actually needs them.

Plain-language operator meaning: $loop already carries both "keep working until the real goal is done" and "use delegated Codex agents when useful and available." Do not wait for a second user sentence to unlock delegation.

Non-Negotiable Invariants

• Treat the $loop / $agent-loop operator token itself as an affirmative

grant to use delegated spawn_agent lanes when the tool exists and delegation materially helps. Do not wait for a second user message that separately says "use agents"; the loop invocation already carries that authority.

• Read the operator literally: $loop semantically means "continue toward the

goal and use agents when they help." If that implication is not visible in the current plan, receipts, or docs, repair those artifacts instead of treating delegation as unapproved.

• Interpret user follow-ups such as 계속, 계속 진행해, or 마무리해 inside an

active $loop run as continuation under that same delegation grant, not as a fresh permission checkpoint for agent use.

• Treat bare implementation-oriented $loop as continuation_mode=nonstop.
• Treat $loop / $agent-loop as standing authorization to use delegated

spawn_agent lanes when delegation materially helps and the host exposes the tool. Do not ask a separate "open agents?" / "use agents?" permission question inside a $loop run; dispatch them with the resolved model pin, or record the concrete runtime blocker.

• Treat commit execution as withheld by default. A normal $loop, $agent-loop,

계속, 계속 진행해, "resume", or "finish the remaining work" instruction authorizes implementation and verification, but does not authorize any actual commit operation. Do not run git add, git commit, git commit -a, npm run loop:commit:auto, or any other commit broker/commit command unless the user gives a fresh explicit commit instruction containing $loop 커밋. Until then, keep verified changes in the working tree and report them as pending commit-broker work instead of starting the broker.

• Cap delegated Codex challenge/proof panels at the phase-required lane count:

five lanes for material initial research and final halt/completion proof; five lanes for planning, pre/post implementation challenge, and verification challenge panels; two lanes for mandatory mini plan validation. Do not expand beyond the phase contract for difficulty, convenience, or retry pressure.

• Treat the first accepted working goal as standing authority to continue; do

not ask whether to keep going, whether to resume after a progress report, or whether to open the next cycle unless a real external approval gate blocks execution.

• Keep working until a real blocker, explicit external authority, or forced host

turn boundary exists.

• Define "real blocker" narrowly. Missing stop/completion proof, incomplete or

timed-out challenge lanes, manual commit/index ownership, approval-needed-only states, and self-assessed no-bounded-action claims are continuation states until a fresh stop-authorization challenge attempt, concrete tool/runtime blocker, or direct explicit user stop proves otherwise.

• In same_turn_only hosts, a visible final reply with run_decision=continue

is bookkeeping for a forced boundary, not semantic stop. $loop only stops semantically after the required fresh 5-lane final proof or a direct explicit user stop.

• Treat auto_resume_any_followup as a forced-boundary recovery fallback, not

as an acceptable nonstop user experience. If the user says that waiting for a follow-up message itself is the defect, classify the event as host_boundary_wait_defect, repair the loop-control contract or run artifacts, and immediately run the next tool-backed action. Do not answer with another receipt-only message while tools remain available.

• A controller must not voluntarily end a turn because a future follow-up could

resume the run. While tool calls are still available, continue the current bounded implementation, verification, inspection, or artifact-repair action. Reserve a visible run_decision=continue receipt for a concrete host/API boundary after recording the boundary evidence.

• Repeat ideation -> research -> plan -> execute -> verify -> reassess until

fresh unanimous 5-lane completion proof exists or a direct explicit user stop overrides.

• Treat initial Research and Plan lock as mandatory gates for material or

uncertain work. A tier0/tier1 deterministic fast path may skip delegated initial research only when the source request is exact, the change is local and reversible, no external/API/DB/security behavior is touched, and the run records fast_path_reason, a minimal revised-plan.md, requirement trace, and local verification. An ordinary tier1_local self-check may also skip delegated initial research only when it records tier1_self_check=pass, risk_expanded=false, implementation summary, verification plan, requirement trace, local verification result/ref, scoped files, and explicit no external/API/DB/security/shared-boundary scope. These paths accept the local implementation batch; they do not by themselves authorize a semantic $loop terminal stop. When an exact tier0/tier1 goal has no remaining stages after local verification, dispatch the final source-first completion proof immediately against the compact source/plan/evidence packet instead of inventing extra research or implementation work.

• Treat handoff.md as continuation state, not as stop permission.
• Treat npm run loop:handoff, a refreshed handoff, or a verified local batch

as a reassessment checkpoint only. If the live state reports run_decision=continue or completionStopAllowed=false, the next controller transition must be one of: start a concrete bounded action, dispatch the required stop/completion challenge, record a canonical no-bounded-action blocker, or emit validated forced-boundary gate output. A normal final recap is not one of the allowed transitions.

• If the controller feels ready to send final because "the current batch is

verified", first classify that impulse as pre_final_reassessment_required. Re-open handoff.md; when any remaining required stage exists, immediately start the next stage or record why it cannot be started with concrete tool evidence.

• If completionStopAllowed=false, any free-form final response is a

voluntary_turn_close unless it is exactly the canonical forced-boundary gate output. A summary that lists remaining work is still an illegal semantic stop because it makes the next action future-tense instead of in-flight.

• Treat any failed loop-final-guard, closeout_gate.py,

validate_continue_reply.py, handoff validation, or explicit completionStopAllowed=false check as a continuation/repair trigger, not as user-visible status material. Do not emit a normal final answer that says a guard blocked completion "as expected" or lists remaining stages as a recap. The next transition must start a bounded tool-backed action, repair the loop controller/artifacts, dispatch a required challenge, or record a canonical no-bounded-action blocker with evidence.

• Keep one authoritative revised-plan.md and one authoritative handoff.md.
• Keep exactly one working goal per run. If a later user turn opens a

materially different $loop / $agent-loop goal, create or resume a new authoritative sibling run immediately instead of silently keeping the older run as the live authority.

• Resolve every run's work_type separately from run_intent. Valid work

types are implementation, research, docs, planning, review, and mixed; non-code work must use a typed completion subject instead of being forced through repo_diff semantics.

• Bind terminal completion to a current completion_subject and selected

run_authority_record. For mixed work, require a composite_subject that covers every required stage subject and digest.

• Select the live run through the authority record, not through stale

conversation memory or a convenient handoff.md. Ambiguous, duplicate, moved, mismatched, or incompatible runs are quarantine candidates and cannot authorize terminal stop.

• Treat authority revision/epoch and digest freshness as stop gates. Terminal

completion must reread the authority record, recompute current source, subject, composite, and stage-graph digests, pass conformance/version checks, and complete with a CAS-style state transition backed by a separate authority_transition_receipt_version=v1 pre/post digest receipt.

• Aggregate challenge results only from one current cycle where every required

lane reviewed the exact same digest set under the same schema, policy, prompt, validator, authority revision, and authority epoch. Do not combine old ALLOWs, partial reruns, mixed-version lane results, or dispatch receipts that do not bind the same phase, challenge mode, source digest, authority revision/epoch, and cycle id.

• Project manifests and agent_loop_override entries are adapters, not global

semantics. Overrides are allowlist-only and may not alter work-type resolution, lane roles, verdict meanings, final proof semantics, model policy, stop gates, challenge aggregation, artifact digest rules, authority fencing, or visible-output contracts.

• A project-discovered $loop improvement must pass portability

classification before promotion: global_invariant, project_adapter_rule, project_local_hint, or rejected_local_hack. Only global_invariant may change global loop semantics.

• Expand explicit sequential user objectives into required stages and do not stop

after only the first one.

• Treat status requests as live-state reporting, not as pause or stop

authorization.

• Treat interruption-style requests such as "잠깐만 지금 하는 것만 하고 먼저

브리핑해줘", "what remains?", "status first", or "brief me on X" as checkpoint interrupts, not loop termination. Finish any already-started safe command or patch batch, provide the requested live briefing in commentary, then either continue the next bounded local action in the same turn or, if the user immediately redirects, follow the newest instruction without requiring fresh $loop permission.

• Treat "what remains?", "why did you stop?", "you should not have stopped",

and similar correction/status turns inside an active $loop as immediate continuation triggers. Give at most one short live-state sentence in commentary, then run the next concrete tool-backed action in the same turn. Do not answer these turns in final unless a canonical forced-boundary closeout receipt has already proved no bounded local action remains.

• Use canonical scripts for any turn-ending closeout; do not hand-write closeout

prose.

• Do not hand-write a run_decision=continue receipt. If a visible turn end is

truly unavoidable, record the boundary receipt first, then emit only the validated closeout_gate.py output.

• Do not summarize, trim, translate, reorder, or selectively copy

closeout_gate.py stdout. A visible continue receipt is a low-freedom protocol message; the final-channel answer must reproduce the gate output verbatim. If you abridge it, record that as abridged_closeout_gate_output_perceived_stop, repair the loop contract, and continue tool-backed work before any further visible receipt.

• In same_turn_only hosts, a turn-ending continue receipt must surface

stop_status=not_stopped, user_visible_note=사용자 표시용: 멈춘 게 아니라 호스트가 보이는 답변만 한 번 끊은 상태입니다. 다음 메시지는 같은 run 자동 재개 신호입니다., final_copy_policy=copy_closeout_gate_stdout_verbatim_no_summary_no_omission, forced_boundary_note=호스트가 백그라운드 실행을 이어주지 않아 final 채널로 경계 영수증을 남긴 것입니다. 루프는 목표 완료/정지로 처리되지 않았고, 아무 후속 메시지나 보내면 같은 run을 즉시 이어갑니다., host_boundary_effect=visible_turn_only_not_goal_stop, auto_resume_trigger=any_followup_message, followup_resume_policy=auto_resume_any_followup, and an exact resume_command=$loop so any ordinary follow-up can be treated as an immediate continuation rather than a fresh permission checkpoint.

• A blocked_during_attempt continue receipt must also surface Korean

user-facing blocker fields before stop_status: user_visible_status_ko=..., blocked_action_ko=..., needed_condition_ko=..., and human_readable_reason=.... These fields must name the concrete blocked action and the concrete external/user condition. English-only or vague blocker prose is inadmissible.

• If the blocker is not a retryable tool/runtime/quota blocker but an

external-gate-only state where no bounded local action remains, do not emit an auto-resume continue receipt. Run the required completion/stop proof when the source allows external/user-only leftovers as completion; otherwise encode a truthful external-gate pause.

• In same_turn_only hosts, a turn-ending continue receipt is illegal unless

turn_exit_evidence also carries host_boundary_ref= bound to the same closeout_round_id and latest attempt_ref; do not claim a forced visible host boundary without a fresh authority receipt.

• If any ordinary follow-up arrives after such a continue receipt, treat it

as that auto-resume trigger, run scripts/record_resume_event.py --trigger any_followup_message, and immediately continue next_mandatory_action; do not debate whether the previous turn "really" stopped and do not ask for permission to resume.

• If the follow-up says the loop stopped after a syntactically valid

same-turn-only continue receipt, classify it as receipt_only_final_boundary_perceived_stop, not as a permission question. Preserve the latest receipt/handoff evidence, record the resume event, patch or validate the loop-control contract that allowed the perception gap, then run at least one tool-backed repair, verification, or next mandatory action before any further turn-ending receipt. If another receipt is later unavoidable, its user-visible note must explicitly name the final-channel host boundary and the automatic same-run resume trigger instead of relying on machine-readable run_decision=continue alone. A second receipt-only answer in that resumed turn is forbidden while tools are available.

• A receipt_only_final_boundary_perceived_stop is especially inadmissible when

delegated agents are quota-blocked or source-wide gates are resource-busy but any smaller local action remains possible. Quota blockers defer that specific delegated action only; resource preflight blockers defer high-memory commands only. They do not justify a visible final closeout while the controller can still do read-only inspection, loop-control repair, targeted tests, scoped lint/type checks, small UI/UX hardening, artifact updates, or plan/evidence cleanup. After such a user correction, first record the resume event, then patch the loop-control rule or artifact that permitted the premature receipt, and immediately run a bounded local action. Do not emit another closeout_gate.py receipt in that resumed turn merely because the same delegated quota or high-memory blocker still exists.

• Record bottleneck/resource telemetry only when the observation changes

controller behavior: a high-memory or source-wide command is deferred, shrunk, skipped, retried later, or replaced with a smaller local action; a delegated, quota, or tool blocker delays a specific lane; or a closeout/resume defect investigation depends on that blocker. If the run can proceed normally, do not add telemetry merely for completene

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kevin9899
• Source: kevin9899/codex-agent-loop-skill
• License: MIT

Install and usage instructions live in the source repository linked above.