write_file

Instructions

Implementation Reference

• src/tools/file_tools.py:48-109 (handler)

  The write_file function: the actual handler that writes file content with policy checks, logging, backup support, and Script Sentinel scanning.

  def write_file(path: str, content: str, ctx: Context | None = None) -> str:
      """Write full file content with policy checks, logging, and backup support."""
      context_tokens = activate_runtime_context(ctx)
      path = str(pathlib.Path(WORKSPACE_ROOT) / path) if not os.path.isabs(path) else path
  
      try:
          refresh_policy_if_changed()
          path_check = check_path_policy(path, tool="write_file")
          if path_check:
              result = PolicyResult(allowed=False, reason=path_check[0], decision_tier="blocked", matched_rule=path_check[1])
          else:
              result = PolicyResult(allowed=True, reason="allowed", decision_tier="allowed", matched_rule=None)
  
          log_entry = build_log_entry("write_file", result, path=path)
          append_log_entry(log_entry)
          if not result.allowed:
              return f"[POLICY BLOCK] {result.reason}"
  
          backup_location = None
          backup_enabled = bool(POLICY.get("audit", {}).get("backup_enabled", True))
          if backup_enabled and os.path.exists(path):
              backup_location = backup_paths([path])
              if backup_location:
                  append_log_entry(
                      {
                          **log_entry,
                          "source": "mcp-server",
                          "backup_location": backup_location,
                          "event": "backup_created",
                      }
                  )
  
          try:
              with open(path, "w") as f:
                  f.write(content)
          except OSError as e:
              return f"Error writing file: {e}"
  
          sentinel_scan = script_sentinel.scan_and_record_write(path, content, writer_agent_id=AGENT_ID)
          if sentinel_scan.get("flagged"):
              append_log_entry(
                  {
                      **log_entry,
                      "source": "mcp-server",
                      "event": "script_sentinel_flagged",
                      "content_hash": sentinel_scan.get("content_hash", ""),
                      "matched_signatures": sentinel_scan.get("matched_signatures", []),
                      "script_sentinel_mode": POLICY.get("script_sentinel", {}).get("mode", "match_original"),
                      "script_sentinel_scan_mode": sentinel_scan.get("scan_mode", POLICY.get("script_sentinel", {}).get("scan_mode", "exec_context")),
                  }
              )
  
          msg = f"Successfully wrote {len(content)} characters to {path}"
          if backup_location:
              msg += f" (previous version backed up to {backup_location})"
          else:
              msg += " (no content-change backup needed)"
          if sentinel_scan.get("flagged"):
              msg += " (Script Sentinel flagged content)"
          return msg
      finally:
          reset_runtime_context(context_tokens)

• src/server.py:21-31 (registration)

  Registration: write_file is imported from tools and registered as an MCP tool via mcp.tool()(tool) in the server loop.

  for tool in [
      server_info,
      restore_backup,
      execute_command,
      read_file,
      write_file,
      edit_file,
      delete_file,
      list_directory,
  ]:
      mcp.tool()(tool)

• src/tools/__init__.py:1-14 (helper)

  Re-export: write_file is re-exported from src/tools/__init__.py so it can be imported cleanly in server.py.

  from .command_tools import execute_command, server_info
  from .file_tools import delete_file, edit_file, list_directory, read_file, write_file
  from .restore_tools import restore_backup
  
  __all__ = [
      "server_info",
      "execute_command",
      "read_file",
      "write_file",
      "edit_file",
      "delete_file",
      "list_directory",
      "restore_backup",
  ]

• src/server.py:1-47 (schema)

  No explicit schema file; write_file uses inline Python type hints (path: str, content: str, ctx) as implicit schema via FastMCP introspection.

  """Thin MCP entrypoint that wires tool handlers from modular components."""
  
  from mcp.server.fastmcp import FastMCP
  
  import approvals
  from tools import (
      delete_file,
      edit_file,
      execute_command,
      list_directory,
      read_file,
      restore_backup,
      server_info,
      write_file,
  )
  
  approvals.init_approval_store()
  
  mcp = FastMCP("ai-runtime-guard")
  
  for tool in [
      server_info,
      restore_backup,
      execute_command,
      read_file,
      write_file,
      edit_file,
      delete_file,
      list_directory,
  ]:
      mcp.tool()(tool)
  
  
  if __name__ == "__main__":
      mcp.run()

• src/airg_hook.py:11-16 (registration)

  Hook redirect: the Write native tool redirects to mcp__ai-runtime-guard__write_file in the AIRG hook.

  REDIRECTS = {
      "Bash": "mcp__ai-runtime-guard__execute_command",
      "Shell": "mcp__ai-runtime-guard__execute_command",
      "Write": "mcp__ai-runtime-guard__write_file",
      "Edit": "mcp__ai-runtime-guard__edit_file",
      "MultiEdit": "mcp__ai-runtime-guard__edit_file",