homelab/BUG_REPORT.md

# Bug Report: Scribe Agent Tool Permission Mismatch

**Date**: 2025-12-18
**Severity**: High
**Component**: Task Tool / Agent Tooling System

## Issue Summary

The `scribe` sub-agent configuration explicitly declares access to `[Read, Grep, Glob, Edit, Write]` tools in `/home/jramos/homelab/sub-agents/scribe.md`, but when launched via the Task tool, it only receives `[Grep, Glob, Edit]` - missing critical `Read` and `Write` tools.

## Expected Behavior

When launching a sub-agent via the Task tool, the agent should receive all tools listed in its configuration file under the `tools:` directive.

From `sub-agents/scribe.md` line 9:
```yaml
tools: [Read, Grep, Glob, Edit, Write]
```

## Actual Behavior

When the scribe agent is launched, it reports:
> "I sincerely apologize for this limitation. The documentation content is ready and comprehensive - I just cannot execute the file operations with my current restricted toolset (Grep, Glob, Edit only - no Write, no Read)."

The agent is NOT receiving:
- `Read` tool (cannot read files for context)
- `Write` tool (cannot create new documentation files)

## Impact

**Critical workflow disruption**: The scribe agent's primary purpose is documentation creation and maintenance. Without the Write tool, it cannot:
- Create new README.md files
- Create service documentation
- Generate architecture diagrams in new files

Without the Read tool, it cannot:
- Verify current infrastructure state
- Cross-reference existing documentation
- Understand context before updating

## Reproduction Steps

1. Create a sub-agent configuration with `tools: [Read, Grep, Glob, Edit, Write]`
2. Launch the agent via Task tool with `subagent_type: scribe`
3. Attempt to use Write tool to create a new file
4. Agent reports tool is unavailable

## Configuration Evidence

**File**: `/home/jramos/homelab/sub-agents/scribe.md`

Lines 9-10:
```yaml
tools: [Read, Grep, Glob, Edit, Write]
model: haiku-4.5
```

Lines 27-33 (Scribe's own documentation):
```markdown
**CRITICAL TOOL INSTRUCTIONS:**
You possess a `Write` tool. You must use it correctly:

1.  **To Create a New File**: Use the `Write` tool.
    * *Do not* attempt to use `Edit` on a non-existent file.
    * *Do not* say "I cannot create files." You have the `Write` tool specifically for this.
    * If you think you don't have the `Write` tool, **CHECK AGAIN**. It is authorized in your configuration.
```

The scribe configuration explicitly expects Write tool access, but the runtime environment doesn't provide it.

## Workaround

Use the `lab-operator` agent instead, which has `[Bash, Read, Grep, Glob, Edit, Write]` tools and successfully receives all declared tools at runtime.

## Additional Context

- **Other affected agents**: Unknown - need to test `backend-builder`, `lab-operator`, and `librarian`
- **Main agent**: Has access to all tools without restriction
- **Agent launch mechanism**: Task tool with `subagent_type` parameter
- **Agent configs location**: `/home/jramos/homelab/sub-agents/*.md`

## Recommended Fix

Investigate the Task tool's agent initialization logic to ensure it properly grants all tools listed in the agent's YAML frontmatter configuration. The tool permission system should honor the declarative configuration without filtering.

## Test Case

```bash
# Verify each agent receives its declared tools
for agent in scribe lab-operator backend-builder librarian; do
    echo "Testing $agent..."
    # Launch agent and check available tools
done
```

Expected: Each agent receives exactly the tools listed in its `tools: []` configuration.

---

**Reporter**: Main Agent (Claude Code)
**Priority**: High - Breaks core documentation workflow
**Status**: Open