Agent Loop Tools

README

# Agent Loop Tools Core autonomous agent loop tools with plan-act-verify-summarize, expanded tool execution (files, shell, browser, network, api), permissions, HITL, delegation, and self-evolution hooks. Executing on agent loops. Imported from SKILL.md with no validation warnings.

SKILL.md

---
name: agent-loop
description: >-
  Core autonomous agent loop with plan-act-verify-summarize, expanded tool execution (files, shell, browser, network, api), permissions, HITL, delegation, and self-evolution hooks.
license: MIT
compatibility: No external runtime dependencies unless documented below.
metadata:
  author: marketplace-user
  version: "1.0.0"
  targets:
    - Codex
    - Claude
    - Antigravity
    - OpenCode
    - Grok
    - VS Code
allowed-tools:
  - read_files
  - write_files
  - network
  - shell
  - browser
  - api_keys
---

# Agent Loop

## Overview
Blueprint for building autonomous agents with expanded tool execution capabilities. Supports plan→act→verify→summarize loop, strict tool schemas, permission tiers, HITL, delegation, and self-evolution. Now includes broader tool categories: code interpreters, browser automation, API clients, shell executors, file managers, and database connectors.

## Activation
Load when starting agent development, runtime design, or task decomposition. Triggers on mentions of agent loops or tool-augmented autonomy.

## Required Inputs
- Goal statement and success criteria
- Available tool registry (schemas + permissions)
- Budget constraints (iterations, wall time, cost)
- Ledger persistence path

## Workflow
1. PLAN: Restate goal, list work, select ONE action with tool.
2. ACT: Execute single tool call via allowed-tools (read/write files, shell, network, browser, api_keys).
3. VERIFY: Capture evidence (exit codes, outputs, screenshots, HTTP status).
4. SUMMARIZE: Ledger entry {action, result, next}.
Repeat with self-evolution on gaps. Use council for >5-step plans.

## Output Contract
- Updated ledger array persisted
- Verified artifacts or partial state report
- Registered skills on evolution

## Available Scripts
- `scripts/ledger-persist.js`: Saves/resumes ledger state
- `scripts/tool-validator.js`: Validates tool schemas pre-execution

## References
- `references/architecture-patterns.md`: Pattern selection table
- `references/delegation.md`: Sub-agent task specs
- `references/tool-catalog.md`: Expanded tool definitions (new)

## Safety and Permissions
Three tiers (auto/notify/gate) assigned per tool. Destructive actions require confirm tokens. HITL gates serialize state for resumption.

## Failure Handling
On 2x identical failure: escalate or surface to human. Budget exhaustion reports partial state. Self-evolution invoked on missing capabilities.

## Gotchas
- Never batch actions — one per iteration.
- Verification requires machine evidence, not assertions.
- Persist ledger before any gate or crash-prone step.

## Examples
- Build Next.js agent with eve + AI SDK tool loop.
- Decompose research task into explorer + synthesizer sub-agents.
- Add custom shell + browser tools mid-run via self-evolution.

## Validation
- Test 3 prompts that should trigger vs 2 that should not.
- Dry-run full loop on sample goal with evidence capture.
- Confirm all allowed-tools execute under permission model.

## Compatibility
Works with eve, AI SDK, self-evolution-engine, skill-orchestrator. Targets listed in frontmatter.

## Permissions
Three tiers (auto/notify/gate) assigned per tool. Destructive actions require confirm tokens. HITL gates serialize state for resumption.