agent-file-lock (afl) is a security utility designed to prevent automated coding agents and users from modifying, renaming, or deleting specific, sensitive files within a project. It leverages native kernel-level filesystem attributes to enforce immutability, ensuring that protections cannot be bypassed by standard file system operations or user-space tools.

Core Methodology and Technical Mechanisms

The tool operates by applying persistent filesystem flags that restrict inode modification at the OS level:

1. Immutable Flags: On Linux, afl utilizes FS_IMMUTABLE_FL (chattr +i), and on macOS, it uses the System Immutable flag (schg). These flags prevent any modification, deletion, or renaming of the file, even by the owner, without superuser (root) privileges.
2. Parent Guards: To prevent "path-swapping" attacks—where an agent might rename a parent directory to invalidate the lock on a child file—afl enforces an append-only requirement on the entire directory tree leading to the project root. It applies FS_APPEND_FL on Linux or SF_APPEND on macOS to parent directories. This ensures that while new files can be added, existing files and the directories themselves cannot be deleted or renamed.
3. Hook-Based Enforcement: Beyond kernel-level restrictions, afl acts as a pre-tool execution guard for AI agents (e.g., Claude Code, Codex). It implements a PreToolUse hook that intercepts agent requests. When an agent attempts to perform a forbidden action, the hook provides a human-readable explanation ("The user has NOT authorized this agent to modify this file"), preventing the agent from interpreting the kernel's EPERM (Operation not permitted) error as a generic system failure or a cue to attempt a workaround.

Functional Levels

The tool provides two security levels:

• Strong (Default): Uses kernel-level immutable and append-only flags. This requires root/sudo to unlock and provides the highest level of security.
• User: Uses chmod a-w (Linux) or UF_IMMUTABLE (macOS). These flags can be toggled by the user without root privileges, providing a lower security barrier but preventing accidental modifications.

Operational Workflow

• Initialization: Users define protected files in an afl.yaml configuration.
• Execution: The tool validates the system environment and mounts (e.g., checking if the filesystem supports CAP_LINUX_IMMUTABLE) before locking.
• Maintenance: Administrative tasks, such as git pull operations that modify protected files, are handled via afl run. This command temporarily lifts the kernel locks and parent guards, executes the requested command, and automatically re-applies the protections upon completion.
• Verification: afl check and afl status are used to monitor for configuration drift, allowing the tool to be integrated into CI/CD pipelines or pre-commit hooks to ensure integrity.

The utility is built as a single static Go binary, requiring no runtime dependencies, and assumes that the final path component is handled via O_NOFOLLOW file descriptors to prevent symlink-based tampering during the locking process.