v0.4.0: Hooks, Compaction, Context Tools, Benchmarks

What's New

Deterministic Loop Hooks

• BaseStartHook / BaseEndHook for injecting instructions before the first LLM call and resuming the loop when the agent would stop
• PlanningHook (forces task planning) and CompletionCheckHook (verifies todo completion before allowing stop)
• Composable TerminationCondition with | / & operators

Context Compaction Strategies

• CompactionStrategy protocol called before each LLM call
• HeadTailCompaction preserves system prompt + recent work while dropping middle messages, respecting atomic groups (tool calls + results stay together)
• SlidingWindowCompaction keeps system message + most recent messages
• NoCompaction baseline for benchmarking
• Token counting via tiktoken with character-estimation fallback

Context Engineering Tools

• TaskTool for spawning sub-agents in isolated contexts
• TodoWriteTool / TodoReadTool / TodoListSessionsTool for file-backed task tracking
• SkillsTool for progressive disclosure via SKILL.md files
• MultiEditTool for atomic multi-file edits
• Factory function create_context_engineering_tools()

Benchmark CLI

• picoagents benchmark list|run|results CLI commands
• Built-in datasets (coding_v1, repo_analysis_v1)
• AgentConfig for declarative agent configuration comparison
• BenchmarkRunner, BenchmarkMiddleware, and analysis formatters

Other

• Instruction presets: get_instructions() for loading reusable system prompt templates
• Built-in skills: Code-review skill with SKILL.md frontmatter format
• From-scratch examples: Four progressive files building a minimal agent from zero

Install

pip install picoagents==0.4.0