Docs updates

Author: ddebowczyk

docs-build/cookbook/agents/agent_builder/agent_basic.mdx

@@ -2,8 +2,8 @@
 title: 'Basic Agent Usage'
 docname: 'agent_basic'
 order: 1
+id: '67ca'
 ---
-
 ## Overview
 
 The simplest use of an Agent - a straightforward Q&A without tools. The agent uses
@@ -13,7 +13,8 @@ a message, processing it through the LLM, and returning a response.
 Key concepts:
 - `AgentBuilder`: Constructs configured agent instances
 - `AgentState`: Immutable state container for messages and metadata
-- `Agent::execute()`: Executes the agent loop until completion
+- `AgentLoop::execute()`: Executes the agent loop until completion
+- `UseGuards`: Adds step/token/time safety limits
 - `AgentConsoleLogger`: Provides visibility into agent execution stages
 
 
@@ -23,7 +24,12 @@ Key concepts:
 <?php
 require 'examples/boot.php';
 
-use Cognesy\Agents\Builder\AgentBuilder;use Cognesy\Agents\Data\AgentState;use Cognesy\Agents\Events\Support\AgentConsoleLogger;use Cognesy\Messages\Messages;
+use Cognesy\Agents\Builder\AgentBuilder;
+use Cognesy\Agents\Capability\Core\UseGuards;
+use Cognesy\Agents\Capability\Core\UseLLMConfig;
+use Cognesy\Agents\Data\AgentState;
+use Cognesy\Agents\Events\Support\AgentConsoleLogger;
+use Cognesy\Messages\Messages;
 
 // Create a console logger for visibility into agent execution
 $logger = new AgentConsoleLogger(
@@ -34,7 +40,8 @@ $logger = new AgentConsoleLogger(
 
 // Build a basic agent
 $agent = AgentBuilder::base()
-    ->withLlmPreset('anthropic')
+    ->withCapability(new UseLLMConfig(preset: 'anthropic'))
+    ->withCapability(new UseGuards(maxSteps: 3, maxTokens: 4096, maxExecutionTime: 30))
     ->build()
     ->wiretap($logger->wiretap());
 
@@ -49,10 +56,16 @@ echo "=== Agent Execution Log ===\n\n";
 $finalState = $agent->execute($state);
 
 echo "\n=== Result ===\n";
-$response = $finalState->currentStep()?->outputMessages()->toString() ?? 'No response';
+$response = $finalState->finalResponse()->toString() ?: 'No response';
 echo "Answer: {$response}\n";
 echo "Steps: {$finalState->stepCount()}\n";
 echo "Tokens: {$finalState->usage()->total()}\n";
 echo "Status: {$finalState->status()->value}\n";
+
+// Assertions
+assert($finalState->status() === \Cognesy\Agents\Enums\ExecutionStatus::Completed);
+assert(!empty($finalState->finalResponse()->toString()), 'Expected non-empty response');
+assert($finalState->stepCount() >= 1, 'Expected at least 1 step');
+assert($finalState->usage()->total() > 0, 'Expected token usage > 0');
 ?>
 ```

docs-build/cookbook/agents/agent_builder/agent_file_system.mdx

@@ -2,8 +2,8 @@
 title: 'Agent with File System Tools'
 docname: 'agent_file_system'
 order: 2
+id: '2b2f'
 ---
-
 ## Overview
 
 Agents can be equipped with file system capabilities to read, write, search, and edit files
@@ -12,7 +12,8 @@ refactoring assistance, and other file-based operations. The agent determines wh
 operations to perform based on the task.
 
 Key concepts:
-- `UseFileTools`: Capability that adds file system tools to the agent
+- `UseFileTools`: Capability that adds core file tools (`read_file`, `write_file`, `edit_file`)
+- `UseTools`: Adds extra tools explicitly when needed (`list_dir`, `search_files`)
 - Working directory: Root path for all file operations (security boundary)
 - Available tools: `read_file`, `write_file`, `edit_file`, `list_dir`, `search_files`
 - `AgentConsoleLogger`: Provides visibility into agent execution stages
@@ -23,7 +24,15 @@ Key concepts:
 <?php
 require 'examples/boot.php';
 
-use Cognesy\Agents\Builder\AgentBuilder;use Cognesy\Agents\Capabilities\File\UseFileTools;use Cognesy\Agents\Data\AgentState;use Cognesy\Agents\Events\Support\AgentConsoleLogger;use Cognesy\Messages\Messages;
+use Cognesy\Agents\Builder\AgentBuilder;
+use Cognesy\Agents\Capability\Core\UseGuards;
+use Cognesy\Agents\Capability\Core\UseTools;
+use Cognesy\Agents\Capability\File\ListDirTool;
+use Cognesy\Agents\Capability\File\SearchFilesTool;
+use Cognesy\Agents\Capability\File\UseFileTools;
+use Cognesy\Agents\Data\AgentState;
+use Cognesy\Agents\Events\Support\AgentConsoleLogger;
+use Cognesy\Messages\Messages;
 
 // Create console logger for execution visibility
 $logger = new AgentConsoleLogger(
@@ -39,6 +48,11 @@ $workDir = dirname(__DIR__, 3);  // Project root
 // Build agent with file system capabilities
 $agent = AgentBuilder::base()
     ->withCapability(new UseFileTools($workDir))
+    ->withCapability(new UseTools(
+        ListDirTool::inDirectory($workDir),
+        SearchFilesTool::inDirectory($workDir),
+    ))
+    ->withCapability(new UseGuards(maxSteps: 8, maxTokens: 8192, maxExecutionTime: 45))
     ->build()
     ->wiretap($logger->wiretap());
 
@@ -62,10 +76,15 @@ echo "=== Agent Execution Log ===\n\n";
 $finalState = $agent->execute($state);
 
 echo "\n=== Result ===\n";
-$response = $finalState->currentStep()?->outputMessages()->toString() ?? 'No response';
+$response = $finalState->finalResponse()->toString() ?: 'No response';
 echo "Answer: {$response}\n";
 echo "Steps: {$finalState->stepCount()}\n";
 echo "Tokens: {$finalState->usage()->total()}\n";
 echo "Status: {$finalState->status()->value}\n";
+
+// Assertions
+assert(!empty($finalState->finalResponse()->toString()), 'Expected non-empty response');
+assert($finalState->stepCount() >= 1, 'Expected at least 1 step');
+assert($finalState->usage()->total() > 0, 'Expected token usage > 0');
 ?>
 ```

docs-build/cookbook/agents/agent_builder/agent_hooks.mdx

@@ -2,8 +2,8 @@
 title: 'Agent Hooks - Tool Interception'
 docname: 'agent_hooks'
 order: 4
+id: '9185'
 ---
-
 ## Overview
 
 Hooks allow you to intercept tool calls before and after execution. This example
@@ -14,7 +14,7 @@ Key concepts:
 - `CallableHook`: Wraps a closure as a hook
 - `HookContext`: Provides access to tool call and agent state
 - `HookTriggers`: Defines when the hook fires (e.g., `beforeToolUse()`)
-- `addHook()`: Registers a hook on the builder with priority
+- `UseHook`: Registers a hook capability with explicit trigger/priority
 - `AgentConsoleLogger`: Provides visibility into agent execution stages
 
 ## Example
@@ -23,7 +23,15 @@ Key concepts:
 <?php
 require 'examples/boot.php';
 
-use Cognesy\Agents\Builder\AgentBuilder;use Cognesy\Agents\Capabilities\Bash\UseBash;use Cognesy\Agents\Data\AgentState;use Cognesy\Agents\Events\Support\AgentConsoleLogger;use Cognesy\Agents\Hook\Collections\HookTriggers;use Cognesy\Agents\Hook\Data\HookContext;use Cognesy\Agents\Hook\Hooks\CallableHook;
+use Cognesy\Agents\Builder\AgentBuilder;
+use Cognesy\Agents\Capability\Bash\UseBash;
+use Cognesy\Agents\Capability\Core\UseGuards;
+use Cognesy\Agents\Capability\Core\UseHook;
+use Cognesy\Agents\Data\AgentState;
+use Cognesy\Agents\Events\Support\AgentConsoleLogger;
+use Cognesy\Agents\Hook\Collections\HookTriggers;
+use Cognesy\Agents\Hook\Data\HookContext;
+use Cognesy\Agents\Hook\Hooks\CallableHook;
 
 // Create console logger for execution visibility
 $logger = new AgentConsoleLogger(
@@ -43,18 +51,30 @@ $blockedPatterns = [
     'dd if=',
     ':(){:|:&};:',  // Fork bomb
 ];
+$blockedPatterns = array_map(
+    static fn(string $pattern): string => strtolower(trim($pattern)),
+    $blockedPatterns,
+);
 
 // Build agent with bash capability and security hook
 $agent = AgentBuilder::base()
     ->withCapability(new UseBash())
-    ->addHook(
+    ->withCapability(new UseHook(
         hook: new CallableHook(function (HookContext $ctx) use ($blockedPatterns): HookContext {
             $toolCall = $ctx->toolCall();
             if ($toolCall === null) {
                 return $ctx;
             }
 
-            $command = $toolCall->args()['command'] ?? '';
+            $args = $toolCall->args();
+            $rawCommand = match (true) {
+                is_array($args) && isset($args['command']) && is_string($args['command']) => $args['command'],
+                default => '',
+            };
+            $command = strtolower(trim((string) preg_replace('/\s+/', ' ', $rawCommand)));
+            if ($command === '') {
+                return $ctx;
+            }
 
             // Check for dangerous patterns
             foreach ($blockedPatterns as $pattern) {
@@ -64,12 +84,13 @@ $agent = AgentBuilder::base()
                 }
             }
 
-            echo "         [HOOK] ALLOWED - {$command}\n";
+            echo "         [HOOK] ALLOWED - {$rawCommand}\n";
             return $ctx;
         }),
         triggers: HookTriggers::beforeToolUse(),
         priority: 100,       // High priority = runs first
-    )
+    ))
+    ->withCapability(new UseGuards(maxSteps: 8, maxTokens: 4096, maxExecutionTime: 30))
     ->build()
     ->wiretap($logger->wiretap());
 
@@ -82,7 +103,7 @@ echo "=== Test 1: Safe Commands ===\n\n";
 $finalState = $agent->execute($state);
 
 echo "\n=== Result ===\n";
-$response = $finalState->currentStep()?->outputMessages()->toString() ?? 'No response';
+$response = $finalState->finalResponse()->toString() ?: 'No response';
 echo "Answer: {$response}\n";
 echo "Steps: {$finalState->stepCount()}\n";
 echo "Status: {$finalState->status()->value}\n";
@@ -100,12 +121,17 @@ $hasErrors = $finalState2->currentStep()?->hasErrors() ?? false;
 echo "Command was " . ($hasErrors ? "BLOCKED (security hook worked!)" : "executed") . "\n";
 echo "Steps: {$finalState2->stepCount()}\n";
 echo "Status: {$finalState2->status()->value}\n";
+
+// Assertions
+assert(!empty($finalState->finalResponse()->toString()), 'Expected non-empty response from safe commands');
+assert($finalState->stepCount() >= 1, 'Expected at least 1 step for safe commands');
+assert($finalState2->stepCount() >= 1, 'Expected at least 1 step for dangerous command test');
 ?>
 ```
 
 ## How It Works
 
-1. **Hook Registration**: `addHook()` registers a `CallableHook` with `HookTriggers::beforeToolUse()`
+1. **Hook Registration**: `UseHook` registers a `CallableHook` with `HookTriggers::beforeToolUse()`
 2. **Context Access**: `HookContext` provides `toolCall()` and `state()` accessors
 3. **Priority**: Higher priority (100) ensures this security check runs before other hooks
 4. **Blocking**: `$ctx->withToolExecutionBlocked($reason)` blocks the tool call with a reason
@@ -115,7 +141,7 @@ echo "Status: {$finalState2->status()->value}\n";
 
 ```php
 // After tool execution - for logging/metrics
-->addHook(
+->withCapability(new UseHook(
     hook: new CallableHook(function (HookContext $ctx): HookContext {
         $exec = $ctx->toolExecution();
         if ($exec !== null) {
@@ -124,19 +150,19 @@ echo "Status: {$finalState2->status()->value}\n";
         return $ctx;
     }),
     triggers: HookTriggers::afterToolUse(),
-)
+))
 
 // Before each step - modify state
-->addHook(
+->withCapability(new UseHook(
     hook: new CallableHook(function (HookContext $ctx): HookContext {
         $state = $ctx->state()->withMetadata('step_started', microtime(true));
         return $ctx->withState($state);
     }),
     triggers: HookTriggers::beforeStep(),
-)
+))
 
 // After each step
-->addHook(
+->withCapability(new UseHook(
     hook: new CallableHook(function (HookContext $ctx): HookContext {
         $started = $ctx->state()->metadata()->get('step_started');
         if ($started !== null) {
@@ -146,5 +172,5 @@ echo "Status: {$finalState2->status()->value}\n";
         return $ctx;
     }),
     triggers: HookTriggers::afterStep(),
-)
+))
 ```

docs-build/cookbook/agents/agent_builder/agent_search.mdx

@@ -2,8 +2,8 @@
 title: 'Agent-Driven Codebase Search'
 docname: 'agent_search'
 order: 6
+id: '4e0c'
 ---
-
 ## Overview
 
 Demonstrates how agents can autonomously search codebases by:
@@ -17,7 +17,7 @@ analyzing results without predefined workflows. The agent decides which files to
 based on search results.
 
 Key concepts:
-- `SearchFilesTool`: Search for files by pattern or content
+- `SearchFilesTool`: Search for files by filename/path pattern
 - `ReadFileTool`: Read file contents
 - `UseSubagents`: Spawn specialized subagents for subtasks
 - `AgentConsoleLogger`: Provides visibility into agent execution stages
@@ -28,7 +28,19 @@ Key concepts:
 <?php
 require 'examples/boot.php';
 
-use Cognesy\Agents\AgentTemplate\Definitions\AgentDefinition;use Cognesy\Agents\AgentTemplate\Definitions\AgentDefinitionRegistry;use Cognesy\Agents\Builder\AgentBuilder;use Cognesy\Agents\Capabilities\File\UseFileTools;use Cognesy\Agents\Capabilities\Subagent\UseSubagents;use Cognesy\Agents\Collections\NameList;use Cognesy\Agents\Data\AgentState;use Cognesy\Agents\Events\Support\AgentConsoleLogger;use Cognesy\Messages\Messages;
+use Cognesy\Agents\Builder\AgentBuilder;
+use Cognesy\Agents\Capability\Core\UseGuards;
+use Cognesy\Agents\Capability\Core\UseTools;
+use Cognesy\Agents\Capability\File\ListDirTool;
+use Cognesy\Agents\Capability\File\SearchFilesTool;
+use Cognesy\Agents\Capability\File\UseFileTools;
+use Cognesy\Agents\Capability\Subagent\UseSubagents;
+use Cognesy\Agents\Collections\NameList;
+use Cognesy\Agents\Data\AgentState;
+use Cognesy\Agents\Events\Support\AgentConsoleLogger;
+use Cognesy\Agents\Template\AgentDefinitionRegistry;
+use Cognesy\Agents\Template\Data\AgentDefinition;
+use Cognesy\Messages\Messages;
 
 // Create console logger for execution visibility
 $logger = new AgentConsoleLogger(
@@ -53,20 +65,25 @@ $registry->register(new AgentDefinition(
 
 $registry->register(new AgentDefinition(
     name: 'searcher',
-    description: 'Searches for files matching patterns',
-    systemPrompt: 'You search for files matching patterns. Use glob patterns effectively.',
+    description: 'Searches for files by filename/path patterns',
+    systemPrompt: 'You search for files by filename/path patterns. Use glob patterns effectively.',
     tools: NameList::fromArray(['search_files']),
 ));
 
 // Build main orchestration agent
 $agent = AgentBuilder::base()
     ->withCapability(new UseFileTools($workDir))
+    ->withCapability(new UseTools(
+        ListDirTool::inDirectory($workDir),
+        SearchFilesTool::inDirectory($workDir),
+    ))
     ->withCapability(new UseSubagents(provider: $registry))
+    ->withCapability(new UseGuards(maxSteps: 12, maxTokens: 12288, maxExecutionTime: 90))
     ->build()
     ->wiretap($logger->wiretap());
 
-// Ask a question that requires search
-$question = "Find all test files related to Agent capabilities and tell me what they test";
+// Ask a question that requires search + file reading
+$question = "Find all tool classes (files matching *Tool.php) under packages/agents/src/Capability/File/ and briefly describe what each tool does based on its code.";
 
 $state = AgentState::empty()->withMessages(
     Messages::fromString($question)
@@ -78,10 +95,15 @@ echo "=== Agent Execution Log ===\n\n";
 $finalState = $agent->execute($state);
 
 echo "\n=== Result ===\n";
-$answer = $finalState->currentStep()?->outputMessages()->toString() ?? 'No answer';
+$answer = $finalState->finalResponse()->toString() ?: 'No answer';
 echo "Answer: {$answer}\n";
 echo "Steps: {$finalState->stepCount()}\n";
 echo "Tokens: {$finalState->usage()->total()}\n";
 echo "Status: {$finalState->status()->value}\n";
+
+// Assertions
+assert(!empty($finalState->finalResponse()->toString()), 'Expected non-empty response');
+assert($finalState->stepCount() >= 1, 'Expected at least 1 step');
+assert($finalState->usage()->total() > 0, 'Expected token usage > 0');
 ?>
 ```