feat: Add file-based Human-in-the-Loop (HIL) inbox system for operator-assisted tool workflows

[fresh3nough]

Closes #337

Summary

This PR adds a file-based Human-in-the-Loop (HIL) inbox system that replaces fragile copy-paste workflows (terminal input() / Caido proxy) for passing large tool output back to the agent. Operators can now drop tool output of any size into a shared inbox directory where the agent automatically picks it up.

What Changed

New strix/hil/ package

• input_manager.py -- Core module with request_input(), wait_for_response(), list_pending_requests(), clear_inbox(), and a stateful InputManager class
• HILTimeoutError exception for timeout handling
• inbox/ directory with .gitkeep -- the file-drop zone for operator tool output

Config integration

• Added hil_inbox_path to Config class, overridable via HIL_INBOX_PATH env var

Tool skill updates

• Added "Operator Help" section to all 25 operator-assisted tool .md files with inbox path references and pipe examples

README documentation

• Full categorized list of all 25 operator-assisted tools (Recon, Exploitation, Proxy, Cracking, Network, AD, RE/Forensics)
• In-depth HIL inbox system documentation: architecture, step-by-step flow, code examples, key features, operator workflow, configuration

Tests

• 44 new tests covering request/response lifecycle, timeout, cleanup, config integration, tool .md validation, and module exports
• All 44 new + 69 existing skill tests pass; ruff lint clean

How It Works

strix/hil/inbox/
    req_<task_id>.txt    <-- Agent writes: instructions for the operator
    resp_<task_id>.txt   <-- Operator writes: full tool output

1. Agent determines which tool to run and creates a request file
2. Agent polls the inbox for the response
3. Operator runs the tool and saves output to the response file
4. Agent detects the response, reads content, and continues analysis
5. Both files are cleaned up automatically

Dependencies

Includes code from #334 and #336 as base dependencies (vulnerability skills + 25 tool skills).

Key Commits

• 6c70c09 -- HIL input manager, config, tool md updates, tests
• 4ca9133 -- README documentation (tools list + HIL system docs)

[greptile-apps]

Greptile Summary

This PR successfully implements a file-based Human-in-the-Loop (HIL) inbox system that replaces fragile copy-paste workflows for passing large tool output between operators and agents. The implementation is well-structured with comprehensive documentation and test coverage.

Key Changes:

• New strix/hil/ package with input_manager.py providing request/response file-based communication
• Config integration via hil_inbox_path field with HIL_INBOX_PATH env var override
• 44 comprehensive tests covering lifecycle, timeouts, cleanup, and config integration
• Updated all 25 operator-assisted tool skill files with consistent "Operator Help" sections
• Added thorough README documentation covering tool categorization and HIL system architecture

Critical Issue:

• Path traversal vulnerability in task_id parameter (strix/hil/input_manager.py:69) - needs input validation to prevent malicious path construction

Strengths:

• Clean code structure with proper error handling and defensive programming
• Excellent test coverage for normal workflows
• Consistent documentation across all 25 tool files
• Well-designed API with both functional and object-oriented interfaces

Confidence Score: 3/5

• This PR has one critical path traversal vulnerability that must be fixed before merging
• The implementation is well-designed with excellent test coverage and documentation. However, the path traversal vulnerability in task_id parameter handling (line 69 of input_manager.py) is a security issue that needs to be addressed. While task_id is likely agent-generated in practice, proper input validation is essential for defense in depth. Once this validation is added, the PR would be safe to merge.
• Pay close attention to strix/hil/input_manager.py - add input validation for the task_id parameter in request_input() and wait_for_response() functions

Important Files Changed

Filename	Overview
strix/hil/input_manager.py	Core HIL system implementation - has path traversal vulnerability in task_id parameter (lines 69, 101-102) that needs input validation
strix/config/config.py	Added hil_inbox_path config field - clean integration with existing config system
tests/hil/test_input_manager.py	Comprehensive test coverage (44 tests) but missing path traversal security tests
tests/skills/test_tool_skills.py	Thorough validation of all 25 tool skills - frontmatter, HIL sections, and content structure
README.md	Added comprehensive documentation: 25 categorized operator-assisted tools and detailed HIL system docs

_{Last reviewed commit: 6a825d1}

[greptile-apps]

_{37 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

task_id used directly in path construction without validation - could allow path traversal if it contains .. or path separators

Suggested change

	req_file = inbox_dir / f"{_REQ_PREFIX}{task_id}{_FILE_SUFFIX}"
	# Validate task_id to prevent path traversal
	if not task_id or '/' in task_id or '\\' in task_id or '..' in task_id:
	raise ValueError(f"Invalid task_id: {task_id!r}")
	req_file = inbox_dir / f"{_REQ_PREFIX}{task_id}{_FILE_SUFFIX}"

Prompt To Fix With AI

This is a comment left during a code review.
Path: strix/hil/input_manager.py
Line: 69

Comment:
`task_id` used directly in path construction without validation - could allow path traversal if it contains `..` or path separators

```suggestion
    # Validate task_id to prevent path traversal
    if not task_id or '/' in task_id or '\\' in task_id or '..' in task_id:
        raise ValueError(f"Invalid task_id: {task_id!r}")
    req_file = inbox_dir / f"{_REQ_PREFIX}{task_id}{_FILE_SUFFIX}"
```

How can I resolve this? If you propose a fix, please make it concise.