Problem

The write_file tool uses cat > {path} which overwrites the entire file. There is no append-capable tool available. This causes silent data loss for any skill that maintains append-only queues or logs.

Real impact: The inbox skill maintains an append-only JSONL queue (~/inbox/inbox.jsonl). Because no append_file tool exists, the agent uses write_file to add entries — which truncates the file and destroys all prior entries. 14 tracked items were silently lost in production.

Current Behavior

# tools/file_operations.py line 726
write_cmd = f"cat > {self._escape_shell_arg(path)}"

write_file is the only write-capable tool. There is no append mode parameter and no separate append tool.

Proposed Solution

Add an append_file method to ShellFileOperations and expose it as a tool:

# In file_operations.py
def append_file(self, path: str, content: str) -> WriteResult:
    path = self._expand_path(path)
    if _is_write_denied(path):
        return WriteResult(error=f"Write denied: {path} is a protected system/credential file.")
    parent = os.path.dirname(path)
    if parent:
        self._exec(f"mkdir -p {self._escape_shell_arg(parent)}")
    append_cmd = f"cat >> {self._escape_shell_arg(path)}"
    result = self._exec(append_cmd, stdin_data=content)
    # ... same error handling and byte counting as write_file

# In file_tools.py
APPEND_FILE_SCHEMA = {
    "name": "append_file",
    "description": "Append content to a file. Safe for JSONL, logs, and queues. Opens in append mode — existing content is never touched.",
    "parameters": {
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "Path to append to"},
            "content": {"type": "string", "description": "Content to append"}
        },
        "required": ["path", "content"]
    }
}

Why This Matters

cat >> opens with O_APPEND. If interrupted:

• All content before the interrupted write survives intact on disk
• At worst, the last appended line may be partial/truncated
• Earlier entries are fully preserved

This is the correct primitive for any append-only data structure (JSONL queues, log files, event journals).

Alternative Considered

Adding an append parameter to the existing write_file tool. However, the tool description currently says "completely replacing existing content" — changing its semantics risks confusion. A separate tool with a distinct name is clearer and safer for model consumption.

Environment

• Hermes Agent on Ubuntu 24.04 (VPS)
• Production data loss confirmed: 14 inbox entries destroyed by write_file overwrite
• Workaround deployed: skill patched to use terminal tool with cat >> directly