I Read Claude Code's Agent Tooling, Then Built the One That Actually Finishes the Job

Aceasta nu este o poveste despre o călătorie. Este lucrarea completă. Am citit despre instrumentele pentru agenți cărora toată lumea le dă stele pe GitHub, am găsit golul pe care niciunul nu îl umplea și am construit piesa care îl ocupă. Golul nu a fost niciodată legat de accesibilitate. Agenții mei puteau deja să vadă, să facă scrape și să caute. Lucrul care mă costa de fapt ore întregi era un agent care citește tot și totuși nu poate termina o sarcină fără ca eu să stau deasupra lui. Așa că este vorba exact despre asta, în două lecții, fiecare susținută de sursa din care provine, copiată și lipită astfel încât să mă puteți verifica.

Lesson 1: The loop Claude ships is a timer, not a worker.

Claude Code are un /loop încorporat. Oamenii presupun că este un lucrător autonom. Nu este. Descrierea oficială a comenzii, copiată exact din registrul de abilități:

“Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo). Omit the interval to let the model self-pace. When the user wants to set up a recurring task, poll for status, or run something repeatedly on an interval.” (source: Claude Code /loop, official command description)

Citiți-o din nou. Aceasta este întreaga comandă. Repornește un prompt pe baza unui ceas. Nu știe ce înseamnă “gata”. Nu își amintește de ce a eșuat încercarea anterioară. Nu poate anula o modificare pe care tocmai a stricat-o. Este o primitivă fantastică pentru polling și pentru repetiții de tip cron. Nu este un lucru căruia îi puteți înmâna o sarcină cu mai mulți pași și de la care puteți pleca.

Verdictul meu dur după ce l-am pus la muncă reală: ca finisator de sarcini, /loop este un gunoi, și pot fi specific de ce. Nu vă poate spune când a terminat, deoarece nu are conceptul de terminat. Rulează din nou un pas care a trecut deja și repetă un pas care a eșuat deja, deoarece nu își amintește nimic între iterații. Va rula într-o stare stricată pentru totdeauna, deoarece nu verifică niciodată un rezultat și nu face niciodată rollback. Vă va suprascrie munca pe jumătate terminată fără a sta pe gânduri, deoarece nu are nicio barieră de siguranță. Îndreptați-l către o sarcină reală cu mai mulți pași și nu va termina treaba, ci doar va continua să bată la aceeași ușă. Aceasta nu este o insultă la adresa instrumentului. Un temporizator nu a fost niciodată construit pentru a fi un lucrător. Dar golul este real, și este întregul motiv pentru care există /autonom.

Lesson 2: The worker I built, and exactly why it beats /loop.

/autonom este un skill open-source pentru Claude Code, sub licență MIT, un singur fișier Markdown pe care îl aruncați în folderul de abilități: https://github.com/popescugeorgebogdan-debug/autonom. Preia aceeași idee de pornire ca /loop și o finalizează corect: stabilește domeniul de aplicare al sarcinii în mod exhaustiv mai întâi, apoi rulează autonom până la o definiție a termenului gata pe care o mașină o poate verifica efectiv, oprindu-se doar pentru un set fix de bariere de siguranță.

Direct comparison: /loop vs /autonom

Capability	/loop (built-in)	/autonom (mine)
Core behavior	re-fires a prompt on an interval	scope, then autonomous loop, then verified DONE
Definition of “done”	none; runs until you stop it	refuses to start until DONE is a machine-checkable assertion (test rc=0 + assertions>0, endpoint status+body, file matches regex/AST)
Scoping before work	none	asks every outcome-determining question first, one dropdown at a time
Failure memory	none; each tick is blind	keys retries on sha256(intent + error); resets on new information, escalates only on the same repeating failure
Stuck detection	none	strike logic + HYPOTHESIS: forcing-function + per-intent wall-time/token caps + cycle-detection
Undo on breakage	none	git tag before every mutation; git reset --hard on verify-fail; never resets over your uncommitted work
Crash safety	none	atomic state.json single-source-of-truth; wakeup carries a fuse, not the spec; idempotency keys + cross-run error journal
Verification	none	authoritative-signal allowlist; “looks right” and “no errors printed” are explicitly banned
Safety gates	none	push / delete / publish / spend always pause and ask, even mid-run
Spec size	one sentence of behavior	a 150-line contract with a 16-point robustness layer

Asta nu înseamnă că sunt incorect cu /loop. /loop este o singură propoziție și este sincer cu privire la faptul că este o singură propoziție. /autonom este mai detaliat și mai complet pentru că a trebuit să fie: fiecare rând din acel tabel este o măsură de combatere a unui mod în care am văzut o rulare nesupravegheată cum eșuează.

The single most important design choice

Majoritatea wrapper-elor de “agent autonom” copiază cea mai proastă regulă din gen: oprește-te după trei încercări eșuate. Această regulă este greșită, iar urmarea ei aruncă la gunoi rulările care erau pe cale să reușească. Am învățat asta în mod direct. Am urmărit o rulare pe care regula celor trei încercări ar fi oprit-o cum a rezolvat problema la următoarea încercare, deoarece fiecare “eșec” scosese la iveală un nou strat al cauzei reale.

Așa că /autonom nu numără încercările simple. Din contractul propriu al skill-ului:

“Key the STOP counter on the (intent + normalized_error/diagnostic)-hash … INCREMENT the strike count only when an attempt repeats a PRIOR (intent,error) signature … RESET that intent’s strike count to 0 whenever an attempt surfaces a NEW error-hash, a new diagnostic fact, or a new hypothesis that is productive iteration, NOT a strike.” (source: autonom/SKILL.md)

Se oprește din buclă atunci când este cu adevărat blocat și continuă să împingă înainte cât timp încă învață. Această singură distincție reprezintă diferența dintre un lucrător și o roată de hamster.

A confession that explains the whole design

Sunt un maniac al controlului și mi-o asum. La tastatură îmi dădăcesc agenții și îi corectez constant, deoarece fac o mulțime de greșeli și vreau să o prind pe fiecare înainte de a se multiplica. /autonom este pentru cealaltă jumătate a vieții mele: când dorm, sau când sunt plecat și nu pot să supraveghez. Nu am încredere de fapt într-un agent nesupravegheat, așa că mi-am codificat propria paranoie în el. Bariera checkable-DONE, rollback-ul înainte de fiecare modificare, oprirea și întrebarea pentru orice este periculos. Este dădaca pe care am construit-o ca să pot părăsi în sfârșit camera.

Take it

/autonom este MIT și intenționat minuscul. Contractul complet, schema de stare, stratul de robustețe în 16 puncte și checklist-ul per-turn sunt toate în acel singur fișier:

→ https://github.com/popescugeorgebogdan-debug/autonom

Faceți-i fork, goliți-l, îmbunătățiți-l. Dacă rulați agenți nesupravegheați și v-ați întors vreodată la unul care rula fericit în buclă, logica de “a ști când să renunți” singură merită citită.

---

Sources, all verified live for this piece: the Claude Code /loop official command description; and my own autonom/SKILL.md (149 lines canonical, 157 in the published repo). Every quote above is copy-pasted from its source.

Gaps & Elegant Alternatives

What you are missing:

While the state-machine hashing and deterministic git verification resolve standard runaway loops, this architecture remains vulnerable to three specific operational traps:

• The Ghost Pass: If an unexpected tool execution crashes out with a zero exit code (rc=0) but updates nothing, the assertion validator evaluates a false success state.
• State Drift Bloat: Running long-duration iterative runs inside a single workspace without hard token optimization limits causes the state.json history log to consume the active context window, forcing degradation of standard tool performance.
• Lack of Concurrency Guardrails: If manual local tool actions occur concurrently during an active asynchronous execution, git reset --hard will instantly wipe out your local, uncommitted changes without validation.

Elegant Solutions:

• Pre-Flight Lock Files: Implement a filesystem lock script (.autonom.lock) that prevents manual document writes or parallel workspace modifications while an autonomous script lifecycle is executing.
• Transactional Staging Directories: Instead of mutating live code repositories directly, copy target folders to a local transient temporary directory (/tmp/autonom-sandbox). Execute the entire testing array inside this enclosed workspace, syncing back to the primary main workspace exclusively upon hitting an unambiguous checkable-DONE state.
• Deterministic AST Delta Diffing: Supplement simple execution exit codes with an autonomous validation step that executes abstract syntax tree parsing on modified codebase documents. This confirms structural modifications match the original engineering intent before committing runtime mutations.