Subtitle Agent operates on local file systems and accesses the internet to retrieve payloads (ZIP/SRT files). Security is handled rigorously at the boundary.

We use deterministic pathlib.resolve(strict=True) enforcement to guarantee that the agent cannot break out of the target media directory.

In src/core/security.py, the safe_copy function specifically ensures that downloaded payloads are only moved into the user-specified root media directory:

• The base directory is resolved.
• The target destination is checked comprehensively: base in target.parents or base == target.
• If the agent attempts a ../ traversal attack based on malicious zip names, standard library Zip extraction combined with our safe_copy module immediately halts execution.

To prevent destructive overwriting of user-owned files, safe_copy maintains a .subtitle_agent_files manifest in the base directory. The agent is strictly permitted to overwrite files only if they were originally generated by the agent itself.

The agent is granted a constrained list of Python tools via ADK (search_tmdb, get_movie_details, search_subdl, download_and_extract, copy_to_media_library). Arbitrary shell execution (subprocess.run, os.system) is explicitly disabled and prohibited in the agent instruction.

To maintain repository integrity and prevent unauthorized or accidental changes to the production logic, direct pushes to the main branch are strictly prohibited.

• Mandatory Pull Requests: All changes must be submitted via a feature branch and a Pull Request.
• Code Review: Pull Requests must be reviewed and approved before merging.
• Mechanical Enforcement: GitHub Branch Protection rules should be enabled to block all direct pushes and require status checks to pass before merging.