file_tools_write_guards.py 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649
  1. """Write-side safety guards for write_file / patch.
  2. Every guard returns ``None`` when the write may proceed, else an error string
  3. the tool returns verbatim.
  4. Guards, in the order the tools apply them: ``_check_sensitive_path`` (hard
  5. deny), ``_check_binary_document_write``, ``_check_protected_instruction_write``
  6. (ALWAYS ask), ``_check_approval_required_write`` (normal gate),
  7. ``_check_cross_profile_path`` (sandbox-mirror lost-work), ``_is_internal_file_tool_content``.
  8. ``_stale_overwrite_blocker`` (write_file only, under the per-path lock) refuses a
  9. whole-file overwrite of content this task never saw or that changed since.
  10. """
  11. import fnmatch
  12. import os
  13. from pathlib import Path
  14. from agent.file_safety import get_nt_namespace_error
  15. from tools import file_state
  16. from tools.binary_extensions import (
  17. has_binary_extension,
  18. has_opaque_document_extension,
  19. is_pdf_path,
  20. is_sqlite_sidecar,
  21. )
  22. from tools.file_tools_paths import (
  23. _expand_tilde, _resolve_path_for_task, _ssh_path_escapes_home, _terminal_env_type_for_task)
  24. from tools.file_tools_read_tracking import _has_full_write_baseline, _is_own_blind_patch, _read_mtime_drifted
  25. import itertools
  26. # Prefixes matched after realpath. macOS: /private/var mirrors /var — block the
  27. # sensitive subtrees only; a blanket "/private/var/" refuses every temp-file
  28. # write because $TMPDIR, /tmp and /var/folders all realpath there.
  29. _SENSITIVE_PATH_PREFIXES = (
  30. "/etc/", "/boot/", "/usr/lib/systemd/",
  31. "/private/etc/",
  32. "/private/var/db/", "/private/var/root/")
  33. _SENSITIVE_EXACT_PATHS = {"/var/run/docker.sock", "/run/docker.sock"}
  34. # NOTE: these four are a TEST-OVERRIDE surface, not a process cache. Both getters
  35. # resolve per call in production (below) because ``get_hermes_home()`` /
  36. # ``get_config_path()`` are per-turn contextvar-scoped: a multiplexed gateway
  37. # (``gateway.multiplex_profiles: true``) serves many profiles in one process, and
  38. # a process-wide memo would freeze whichever profile's home/config ran first —
  39. # making the protected-instruction gate and the ``config.yaml`` hard-block
  40. # order-dependent, up to letting a later profile rewrite its own ``config.yaml``
  41. # the block exists to protect (#107327). A test can still pin a value by setting
  42. # the slot and its ``_loaded`` flag.
  43. _hermes_config_resolved: str | None = None
  44. _hermes_config_resolved_loaded = False
  45. _real_hermes_home_cached: str | None = None
  46. _real_hermes_home_loaded = False
  47. def _config_path_resolved() -> str:
  48. from hermes_cli.config import get_config_path
  49. return str(get_config_path().resolve())
  50. def _hermes_home_real() -> str:
  51. from hermes_constants import get_hermes_home
  52. return os.path.realpath(str(get_hermes_home()))
  53. def _get_hermes_config_resolved() -> str | None:
  54. """Resolved absolute path of the Hermes config file for the ACTIVE profile.
  55. Resolved per call so it tracks the per-turn ``HERMES_HOME`` scope (#107327);
  56. a test may pin it via ``_hermes_config_resolved`` + ``_hermes_config_resolved_loaded``."""
  57. if _hermes_config_resolved_loaded:
  58. return _hermes_config_resolved
  59. try:
  60. return _config_path_resolved()
  61. except Exception:
  62. # Resolver failure must stay bound to the ACTIVE profile's home, not the
  63. # subprocess HOME. ``_expand_tilde("~/...")`` follows the subprocess-HOME
  64. # contract, which under host ``auto`` mode can be the real/default user
  65. # home rather than the active multiplex ``HERMES_HOME`` — comparing
  66. # beta's ``config.yaml`` against the default/root config would let the
  67. # hard-block fail open on the exception path. Re-derive from the same
  68. # ``get_hermes_home()`` key the happy path uses, and substitute no
  69. # unrelated home if even that is gone (#107327 follow-up; PR #107335).
  70. try:
  71. from hermes_constants import get_hermes_home
  72. return str((Path(str(get_hermes_home())) / "config.yaml").resolve())
  73. except Exception:
  74. return None
  75. def _get_real_hermes_home() -> str | None:
  76. """Realpath of the authoritative Hermes home for the ACTIVE profile.
  77. Resolved per call so it tracks the per-turn ``HERMES_HOME`` scope (#107327);
  78. a test may pin it via ``_real_hermes_home_cached`` + ``_real_hermes_home_loaded``.
  79. Consumers exempting a whole TREE want ``_hermes_exempt_homes()``: under a named
  80. profile this home is ``<root>/profiles/<name>`` and the root is exempt too."""
  81. if _real_hermes_home_loaded:
  82. return _real_hermes_home_cached
  83. try:
  84. return _hermes_home_real()
  85. except Exception:
  86. # Same active-profile binding on the exception path (see
  87. # ``_get_hermes_config_resolved``): re-derive from ``get_hermes_home()``
  88. # rather than ``_expand_tilde("~/.hermes")`` so the protected-instruction
  89. # exemption resolves against the active profile — not the subprocess /
  90. # default home — and substitute no unrelated home if the active security
  91. # path cannot be established (PR #107335). A ``None`` here fails closed at
  92. # the consumer: the ``~/.hermes`` exemption is skipped, so the gate runs.
  93. try:
  94. from hermes_constants import get_hermes_home
  95. return os.path.realpath(str(get_hermes_home()))
  96. except Exception:
  97. return None
  98. def _hermes_exempt_homes() -> tuple[str, ...]:
  99. """Realpaths of the Hermes home tree(s) the protected-instruction gate must stay out of:
  100. the ACTIVE profile's home, plus the Hermes ROOT when that home is a named profile
  101. (``<root>/profiles/<name>``). Exempting only the profile dir left the root's DIRECT files
  102. (LEDGER.md / MEMORY.md / SOUL.md / AGENTS.md ...) to the ``.hermes`` component rule, which
  103. gated them like a project-local ``<repo>/.hermes/config.yaml`` — fail-closed headless
  104. (#110630). They are the agent's own store, governed by their own guards, exactly like
  105. ``~/.hermes`` under the default profile. The root is added only when the shape really is a
  106. named profile (``named_profile_home``), so a coincidental ``profiles/`` dir elsewhere never
  107. exempts its parent; the home comes from the ACTIVE scope, never ``HERMES_HOME`` alone."""
  108. home = _get_real_hermes_home()
  109. if not home:
  110. return ()
  111. try:
  112. from hermes_constants import named_profile_home
  113. profile_home = named_profile_home(home)
  114. except Exception:
  115. profile_home = None
  116. if profile_home is None:
  117. return (home,)
  118. root = os.path.realpath(str(Path(str(profile_home)).parent.parent))
  119. return (home, root) if root and root != home else (home,)
  120. def _resolved_or_raw(filepath: str, task_id: str) -> str:
  121. """Task-resolved path string, falling back to the raw input on resolution failure."""
  122. try:
  123. return str(_resolve_path_for_task(filepath, task_id))
  124. except (OSError, ValueError):
  125. return filepath
  126. def _check_sensitive_path(filepath: str, task_id: str = "default") -> str | None:
  127. """Return an error message if the path targets a sensitive system location."""
  128. # NT/device-namespace guard on the RAW string, BEFORE the task-base join:
  129. # on POSIX a leading "\??\" reads as a relative segment and gets anchored
  130. # under the base dir, hiding the prefix from the resolved-path checks,
  131. # while the same string relayed to a Windows host (remote backend, desktop
  132. # bridge) triggers the NTLM-leak vector. See agent/file_safety.py.
  133. nt_err = get_nt_namespace_error(filepath, verb="Write")
  134. if nt_err:
  135. return nt_err
  136. candidates = (_resolved_or_raw(filepath, task_id), os.path.normpath(_expand_tilde(filepath)))
  137. if _ssh_path_escapes_home(candidates[0]) and _terminal_env_type_for_task(task_id) == "ssh":
  138. return (
  139. f"Refusing to write to {filepath}: it climbs above the SSH home and the remote "
  140. "home could not be detected, so its target cannot be checked. Pass an absolute path.")
  141. if any(c.startswith(_SENSITIVE_PATH_PREFIXES) or c in _SENSITIVE_EXACT_PATHS for c in candidates):
  142. return (
  143. f"Refusing to write to sensitive system path: {filepath}\n"
  144. "Use the terminal tool with sudo if you need to modify system files.")
  145. # approvals.mode and other security settings live in config.yaml; a
  146. # prompt-injected agent could silently disable exec approval by editing it.
  147. hermes_config = _get_hermes_config_resolved()
  148. if hermes_config and hermes_config in candidates:
  149. return (
  150. f"Refusing to write to Hermes config file: {filepath}\n"
  151. "Agent cannot modify security-sensitive configuration. "
  152. "Edit ~/.hermes/config.yaml directly or use 'hermes config' instead.")
  153. from tools.skill_lock import path_refusal
  154. if reason := path_refusal(candidates):
  155. return f"Refusing to write to {filepath}: {reason}"
  156. return None
  157. # ── Protected agent-instruction files (always-ask approval gate) ─────────
  158. # Files that steer FUTURE agent behavior are a prompt-injection persistence
  159. # vector (AGENTS.md / CLAUDE.md / SOUL.md / .cursorrules / project .hermes tree).
  160. # Writes ALWAYS require human approval — even under --yolo — and fail closed
  161. # without a human channel. Basenames match in ANY directory, case-insensitively.
  162. # Ported from: RooCodeInc/Roo-Code RooProtectedController (Apache-2.0). Companion: the terminal-tool vector
  163. # is covered separately (#58631); this gate covers the write_file/patch vector. Symlink lesson from #41351:
  164. # always realpath before matching. Scope decision (documented): basenames match in ANY directory, because
  165. # project-context instruction files are loaded from cwd trees — an AGENTS.md anywhere the agent might later
  166. # run from is a live target. Basenames match case-insensitively so case-variant spellings on
  167. # case-insensitive filesystems (macOS/Windows) cannot slip past; on case-sensitive filesystems most loaders
  168. # probe common case variants too, so the stricter behavior is kept uniform.
  169. _PROTECTED_INSTRUCTION_BASENAMES = frozenset({
  170. "agents.md", "claude.md", "soul.md", ".cursorrules"})
  171. def _protected_instruction_config() -> tuple[bool, list[str]]:
  172. """Return ``(enabled, extra_patterns)`` from ``security.protected_instruction_files`` /
  173. ``security.protected_instruction_extra_patterns`` (fnmatch on basename). Config read
  174. failures keep the gate ON — fail-safe for a security boundary."""
  175. try:
  176. from hermes_cli.config import load_config, cfg_get
  177. cfg = load_config()
  178. enabled = cfg_get(cfg, "security", "protected_instruction_files", default=True)
  179. extra = cfg_get(cfg, "security", "protected_instruction_extra_patterns", default=[])
  180. except Exception:
  181. return True, []
  182. if not isinstance(enabled, bool):
  183. enabled = True
  184. if not isinstance(extra, list):
  185. extra = []
  186. return enabled, [str(p) for p in extra if p]
  187. def _protected_instruction_reason(filepath: str, task_id: str = "default",
  188. *, enabled: bool | None = None,
  189. extra_patterns: list[str] | None = None) -> str | None:
  190. """Return a short label when ``filepath`` targets a protected instruction file, else ``None``.
  191. Matches BOTH the normalized input and its realpath so no symlink direction escapes.
  192. Matching runs on BOTH the normalized input path and its realpath so neither a symlink pointing AT a
  193. protected file (#41351) nor a protected name that is itself a symlink escapes the gate. ``..`` traversal
  194. is neutralized by normpath/realpath before the basename compare.
  195. """
  196. if enabled is None or extra_patterns is None:
  197. enabled, extra_patterns = _protected_instruction_config()
  198. if not enabled:
  199. return None
  200. normalized = os.path.normpath(_expand_tilde(filepath))
  201. try:
  202. resolved = os.path.realpath(str(_resolve_path_for_task(filepath, task_id)))
  203. except (OSError, ValueError, RuntimeError):
  204. resolved = os.path.realpath(normalized)
  205. # ~/.hermes itself is governed by its own guards (config.yaml hard-block,
  206. # mirror guard, write_approval); this gate targets PROJECT-LOCAL files only.
  207. # Must run before the ``.hermes`` component rule, which would match the home.
  208. # ``_hermes_exempt_homes`` also covers the ROOT when the active home is a named
  209. # profile, so ~/.hermes/<file> cannot read as project-local ``.hermes`` config.
  210. for real_home in _hermes_exempt_homes():
  211. if resolved == real_home or resolved.startswith(real_home + os.sep):
  212. return None
  213. for candidate in (normalized, resolved):
  214. base = os.path.basename(candidate)
  215. base_lower = base.lower()
  216. if base_lower in _PROTECTED_INSTRUCTION_BASENAMES or any(
  217. fnmatch.fnmatch(base_lower, pattern.lower()) for pattern in extra_patterns):
  218. return base
  219. # Project-local .hermes config dirs (<repo>/.hermes/config.yaml) steer
  220. # behavior too. Only the IMMEDIATE parent counts — matching any ancestor
  221. # would gate every write inside a checkout living under ~/.hermes.
  222. parts = candidate.replace("\\", "/").rstrip("/").split("/")
  223. if len(parts) >= 2 and parts[-2] == ".hermes":
  224. return candidate
  225. return None
  226. _APPROVAL_UNAVAILABLE = "requires approval but the approval subsystem is unavailable."
  227. _NO_HUMAN = "requires approval but no interactive user or gateway is present to approve it."
  228. def _request_protected_instruction_approval(reasons: list[str], task_id: str = "default") -> str | None:
  229. """Ask the human to approve a write to protected instruction file(s); ``None`` when approved.
  230. Deliberately NOT routed through ``_run_approval_gate`` (honors --yolo and
  231. allowlists): this gate is one-operation approval EVERY time, no persisted
  232. scope, fail-closed without a human channel.
  233. """
  234. targets = ", ".join(dict.fromkeys(reasons))
  235. description = (
  236. f"Write to protected agent-instruction file(s): {targets}. "
  237. "These files steer future agent behavior; approval is always "
  238. "required (not bypassed by auto-approve).")
  239. display = f"<write to {targets}>"
  240. blocked = (
  241. f"BLOCKED: write to protected agent-instruction file(s) ({targets}) "
  242. "{why} The user has NOT consented to this write. Do NOT retry it or "
  243. "attempt the same edit via another path (terminal, execute_code, "
  244. "etc.).")
  245. timed_out = blocked.format(why="approval prompt timed out without a user response. Silence is not consent.")
  246. denied = blocked.format(why="was denied by the user.")
  247. try:
  248. import tools.approval as _approval
  249. from tools.approval_context import _fire_approval_hook, get_current_session_key
  250. from tools.approval_gateway_wait import _await_gateway_decision
  251. from tools.approval_prompt import prompt_dangerous_approval
  252. except Exception:
  253. return blocked.format(why=_APPROVAL_UNAVAILABLE)
  254. # Gateway surface: block on the button round-trip when a notify callback
  255. # is registered for this session. One-operation only — no scope buttons.
  256. session_key = get_current_session_key()
  257. try:
  258. with _approval._lock:
  259. notify_cb = _approval._gateway_notify_cbs.get(session_key)
  260. except Exception:
  261. notify_cb = None
  262. if notify_cb is not None:
  263. approval_data = {
  264. "command": display,
  265. "pattern_key": "protected_instruction_file",
  266. "pattern_keys": ["protected_instruction_file"],
  267. "description": description,
  268. "allow_permanent": False,
  269. "allow_session": False}
  270. decision = _await_gateway_decision(session_key, notify_cb, approval_data, surface="gateway")
  271. if decision.get("notify_failed"):
  272. return blocked.format(why="requires approval but the approval request could not be delivered.")
  273. if decision.get("cancelled"):
  274. return blocked.format(why=f"approval was withdrawn before the user answered ({decision['cancelled']}).")
  275. choice, timed = decision.get("choice"), not decision.get("resolved")
  276. else:
  277. # CLI surface: per-thread approval callback (prompt_toolkit panel).
  278. try:
  279. from tools.terminal_tool import _get_approval_callback
  280. callback = _get_approval_callback()
  281. except Exception:
  282. callback = None
  283. if callback is None:
  284. # No human channel (script, cron, background thread): fail closed —
  285. # auto-approving here would recreate the persistence vector.
  286. return blocked.format(why=_NO_HUMAN)
  287. # -q (every kanban worker), cron and unattended platforms can have a callback registered that nobody
  288. # answers: fail closed now, and never auto-approve, whatever approvals.<context>_mode says.
  289. from tools.approval_context import _no_user_can_answer
  290. if _no_user_can_answer():
  291. return blocked.format(why=_NO_HUMAN)
  292. # Same observer payload as the gateway branch (#131876), fired like the
  293. # dangerous-command CLI prompt in tools/approval.py.
  294. hook_kwargs = dict(command=display, description=description, pattern_key="protected_instruction_file",
  295. pattern_keys=["protected_instruction_file"], session_key=session_key, surface="cli")
  296. _fire_approval_hook("pre_approval_request", **hook_kwargs)
  297. choice = prompt_dangerous_approval(
  298. display, description, allow_permanent=False, allow_session=False, approval_callback=callback)
  299. _fire_approval_hook("post_approval_response", **hook_kwargs, choice=choice)
  300. if choice == "cancelled":
  301. return blocked.format(why="approval prompt could not be delivered or was not answered "
  302. f"({getattr(choice, 'cause', 'no answer')}).")
  303. timed = choice == "timeout"
  304. # Any tapped scope is a one-operation grant; nothing is persisted.
  305. if not timed and choice in {"once", "session", "always"}:
  306. return None
  307. return timed_out if timed else denied
  308. def _check_protected_instruction_write(paths: list[str], task_id: str = "default") -> str | None:
  309. """Gate a write/patch touching protected instruction files. ONE protected file gates
  310. the ENTIRE multi-file patch (one prompt, all-or-nothing)."""
  311. enabled, extra = _protected_instruction_config()
  312. if not enabled:
  313. return None
  314. reasons = [r for r in (_protected_instruction_reason(p, task_id, enabled=enabled, extra_patterns=extra)
  315. for p in paths) if r]
  316. if not reasons:
  317. return None
  318. return _request_protected_instruction_approval(reasons, task_id)
  319. def _check_approval_required_write(paths: list[str], task_id: str = "default") -> str | None:
  320. """Gate a write/patch touching an approval-required path (``~/.ssh/config`` can steer
  321. execution via ``ProxyCommand``). Routine gate: once/session/always, honors --yolo,
  322. fail-closed without an interactive/gateway channel."""
  323. try:
  324. from agent.file_safety import is_write_approval_required
  325. except Exception:
  326. return None
  327. # Resolve against the task's cwd, not the process's: a gateway-hosted turn runs in a
  328. # process whose cwd is not the session workspace, so a relative path would miss the gate.
  329. targets = [p for p in paths if is_write_approval_required(_resolved_or_raw(p, task_id))]
  330. if not targets:
  331. return None
  332. display_targets = ", ".join(dict.fromkeys(targets))
  333. description = (
  334. f"Write to SSH client config file(s): {display_targets}. "
  335. "The SSH config can carry ProxyCommand / Match exec directives that "
  336. "run commands, so writes require your approval.")
  337. blocked = (
  338. f"BLOCKED: write to SSH config file(s) ({display_targets}) "
  339. "{why} Do NOT retry it via another path (terminal, execute_code) "
  340. "without the user's explicit consent.")
  341. try:
  342. import tools.approval as _approval
  343. except Exception:
  344. return blocked.format(why=_APPROVAL_UNAVAILABLE)
  345. result = _approval._run_approval_gate(
  346. pattern_key="ssh_config_write",
  347. description=description,
  348. display_target=f"<write to {display_targets}>",
  349. cron_deny_message=blocked.format(why="requires approval but this cron session denies it."),
  350. single_query_deny_message=blocked.format(
  351. why="requires approval but single-query (-q) sessions run "
  352. "without a user present to approve it. To allow flagged "
  353. "actions in single-query mode, set approvals.single_query_mode: "
  354. "approve in config.yaml."),
  355. autoapprove_log_prefix="ssh_config_write",
  356. fail_closed_when_no_human=True,
  357. no_human_block_message=blocked.format(why=_NO_HUMAN))
  358. if result.get("approved"):
  359. return None
  360. return result.get("message") or blocked.format(why="was denied.")
  361. def _get_container_mirror_prefix_for_task(task_id: str = "default") -> str | None:
  362. """Return the container-side Hermes mirror prefix for persistent Docker file tools."""
  363. try:
  364. from tools.terminal_tool import (
  365. _active_environments, _env_lock, _get_env_config, _resolve_container_task_id)
  366. container_key = _resolve_container_task_id(task_id)
  367. with _env_lock:
  368. env = _active_environments.get(container_key) or _active_environments.get(task_id)
  369. if env is not None:
  370. persistent_docker = (env.__class__.__name__ == "DockerEnvironment"
  371. and bool(getattr(env, "_persistent", False)))
  372. return "/root/.hermes" if persistent_docker else None
  373. config = _get_env_config()
  374. except Exception:
  375. return None
  376. if config.get("env_type") == "docker" and config.get("container_persistent", True):
  377. return "/root/.hermes"
  378. return None
  379. def _check_cross_profile_path(filepath: str, task_id: str = "default") -> str | None:
  380. """Soft-guard: warn when ``filepath`` lands on a host-side or Docker sandbox MIRROR of
  381. Hermes state (a write the host never reads). Not profile isolation — that guard was
  382. removed; ``cross_profile=True`` keeps bypassing this one for replay compat. Fails open."""
  383. try:
  384. from agent.file_safety import get_container_mirror_warning, get_sandbox_mirror_warning
  385. except Exception:
  386. return None
  387. resolved = _resolved_or_raw(filepath, task_id)
  388. warning = get_sandbox_mirror_warning(resolved)
  389. if warning is not None:
  390. return warning
  391. return get_container_mirror_warning(resolved, mirror_prefix=_get_container_mirror_prefix_for_task(task_id))
  392. def _target_regular_file_state(filepath: str, task_id: str = "default") -> str:
  393. """Is a REGULAR file at *filepath* present where the write will execute
  394. (the task's backend, not the controller's disk — #122662)?
  395. Returns ``"exists"``, ``"absent"`` or ``"unavailable"``. Host-backed envs
  396. keep ``Path.is_file`` semantics; anything not proven absent is
  397. ``"unavailable"`` and callers must fail closed.
  398. """
  399. from tools.file_tools import _file_ops_uses_host_paths, _get_file_ops
  400. try:
  401. resolved = str(_resolve_path_for_task(filepath, task_id))
  402. except Exception:
  403. resolved = None
  404. try:
  405. file_ops = _get_file_ops(task_id)
  406. except Exception:
  407. return "unavailable"
  408. if _file_ops_uses_host_paths(file_ops):
  409. # Host writes land on the resolved path, else today's HOST
  410. # ``_expand_tilde`` fallback — probe exactly that string.
  411. probe = _expand_tilde(filepath) if resolved is None else resolved
  412. try:
  413. return "exists" if Path(probe).is_file() else "absent"
  414. except OSError:
  415. return "absent"
  416. try:
  417. # Backend writes land on ``_expand_path(_resolved or path)``: the
  418. # backend's own home for a tilde fallback, never the host's.
  419. _size, status = file_ops._probe_regular_file(file_ops._expand_path(resolved or filepath))
  420. except Exception:
  421. return "unavailable"
  422. if status in ("ok", "bad_size"):
  423. # bad_size: ``[ -f ]`` succeeded, only ``wc`` was unparseable.
  424. return "exists"
  425. if status in ("missing", "not_regular"):
  426. # not_regular: no REGULAR file at the path (dir/FIFO/dangling link) —
  427. # the same answer Path.is_file gives on the host.
  428. return "absent"
  429. return "unavailable"
  430. def _check_binary_document_write(filepath: str, task_id: str = "default") -> str | None:
  431. """Reject text-tool writes that would corrupt a binary document (read_file showed
  432. EXTRACTED text, so the model may write it back). Opaque document formats and
  433. SQLite sidecars (-wal/-shm/-journal) are always rejected; .pdf and every other
  434. BINARY_EXTENSIONS suffix only when OVERWRITING an existing file (raw PDF syntax
  435. is text-authorable and text fixtures named ``*.db`` exist). "Existing" is asked
  436. of the filesystem the write will hit — the task's backend, via
  437. ``_target_regular_file_state`` — never the controller's disk alone (#122662).
  438. ``read_file`` auto-extracts .docx/.xlsx/.pptx (and PDF, via anydoc) to readable text, so the model
  439. plausibly believes it holds the file's contents and tries to write the edited text back with
  440. write_file/patch. A plain-text write can never produce a valid OOXML/OLE/ODF container, so that write
  441. silently destroys the document (port of nearai/ironclaw#7109).
  442. """
  443. ext = os.path.splitext(filepath)[1].lower()
  444. if has_opaque_document_extension(filepath):
  445. return (
  446. f"Refusing to write plain text to binary document '{filepath}' ({ext}). "
  447. "A text write cannot produce a valid document container and would "
  448. "corrupt the file (read_file showed you EXTRACTED text, not the real "
  449. "bytes). Use the microsoft-office skill or a library like "
  450. "python-docx/openpyxl/python-pptx via the terminal to create or edit "
  451. "this document.")
  452. # A -wal/-shm/-journal path is never a legitimate text target, even when
  453. # no sidecar exists yet: a checkpointed db has none on disk, and a garbage
  454. # WAL dropped next to a live database is picked up on the next open.
  455. if is_sqlite_sidecar(filepath):
  456. return (
  457. f"Refusing to write plain text to binary SQLite sidecar '{filepath}' ({ext}). "
  458. "A -wal/-shm/-journal file holds raw database pages that SQLite "
  459. "reads on the next open; text there corrupts the database. Use the "
  460. "sqlite3 CLI or a SQLite library via the terminal to modify the "
  461. "database instead.")
  462. # Overwriting an existing binary (PDF, image, archive, SQLite db, ...)
  463. # with text destroys it — the model only ever saw extracted or mojibake
  464. # text. Creating a NEW file with such an extension stays allowed: raw PDF
  465. # syntax is text-authorable and text fixtures named ``*.db`` exist.
  466. pdf = is_pdf_path(filepath)
  467. if pdf or has_binary_extension(filepath):
  468. state = _target_regular_file_state(filepath, task_id)
  469. if state == "exists":
  470. if pdf:
  471. return (
  472. f"Refusing to overwrite existing PDF '{filepath}' with plain text. "
  473. "read_file showed you EXTRACTED text, not the real bytes — writing "
  474. "text back would destroy the document. Use the pdf skill or a PDF "
  475. "library via the terminal to modify it. (Creating a NEW .pdf file "
  476. "is allowed.)")
  477. return (
  478. f"Refusing to overwrite existing binary file '{filepath}' ({ext}) "
  479. "with plain text — read_file showed you extracted or mojibake "
  480. "text, not the real bytes, and writing text back would destroy "
  481. "the file. Use a binary-aware tool via the terminal to modify it "
  482. "(for SQLite databases, the sqlite3 CLI or a SQLite library). "
  483. "(Creating a NEW file with this extension is allowed.)")
  484. if state == "unavailable":
  485. # Fail closed: absence not proven on the filesystem the write would
  486. # hit, so proceeding could destroy a binary the guard never saw.
  487. return (
  488. f"Refusing to write to '{filepath}': could not establish whether "
  489. "the target file already exists where this write would execute "
  490. "(the terminal environment may be starting, unreachable, or was "
  491. "removed). The file was NOT modified — retry once the environment "
  492. "is reachable.")
  493. return None
  494. # ── Internal display text must never be persisted as file content ────────
  495. _READ_DEDUP_STATUS_MESSAGE = (
  496. "File unchanged since last read. The content from "
  497. "the earlier read_file result in this conversation is "
  498. "still current — refer to that instead of re-reading.")
  499. def _stale_overwrite_blocker(filepath: str, resolved: str | None, task_id: str) -> str | None:
  500. """Reason write_file must NOT replace the existing file, else ``None``.
  501. Refuses BEFORE any disk mutation (the pre-#65604 warning arrived after the
  502. clobber): a sibling/external/partial-read staleness finding, or an existing
  503. file with no full-content baseline for this task (never read in full, read
  504. redacted, only patched without one). Net-new files, files this task fully read
  505. (in one page or by paging contiguously to the last line), wrote, or patched
  506. from such a baseline, unresolvable paths and the file-state kill switch all
  507. let the write proceed.
  508. """
  509. if file_state.guard_disabled():
  510. return None
  511. stale = file_state.check_stale(task_id, resolved) if resolved else None
  512. if stale:
  513. return stale
  514. if _read_mtime_drifted(filepath, task_id):
  515. return (
  516. f"{filepath} was modified since you last read it (external edit or "
  517. "concurrent agent). Re-read the file before writing.")
  518. if not resolved or _has_full_write_baseline(resolved, task_id):
  519. return None
  520. try:
  521. exists = Path(resolved).exists()
  522. except OSError:
  523. return None
  524. if not exists:
  525. return None
  526. if _is_own_blind_patch(resolved, task_id):
  527. return (
  528. "Your patch changed this file without a full view of its current content. Read the current file "
  529. "in full before a whole-file overwrite, or continue with targeted patches.")
  530. return (
  531. f"{resolved} exists but this task has not seen its full current content "
  532. "(never read, patched without a prior full read, or only a redacted/partial view). Read the "
  533. "file — every page of it, if it needs offset/limit — or use patch for a "
  534. "targeted edit; a stale conversation copy must not overwrite the current "
  535. "disk content.")
  536. def _stale_write_refusal(filepath: str, reason: str, resolved: str | None = None) -> dict:
  537. """Model-facing refusal payload for write_file; ``stale_write_blocked`` lets
  538. callers tell it apart from I/O errors."""
  539. result = {
  540. "error": (
  541. f"Refusing to overwrite {filepath}: {reason} "
  542. "The file was NOT modified. Reload the current contents with read_file "
  543. "(every page, for a file that needs offset/limit), merge the requested "
  544. "change, then call write_file again. For small edits, prefer patch so "
  545. "existing unrelated changes are preserved."),
  546. "stale_write_blocked": True,
  547. "path": filepath,
  548. }
  549. if resolved:
  550. result["resolved_path"] = resolved
  551. return result
  552. def _is_internal_file_status_text(content: str) -> bool:
  553. """True when content is the read_file dedup status message, verbatim or lightly framed
  554. (contains the full message and is <=2x its length — a real file quoting it would be longer)."""
  555. if not isinstance(content, str):
  556. return False
  557. stripped = content.strip()
  558. return bool(stripped) and _READ_DEDUP_STATUS_MESSAGE in stripped and (
  559. len(stripped) <= 2 * len(_READ_DEDUP_STATUS_MESSAGE))
  560. def _looks_like_read_file_line_numbered_content(content: str) -> bool:
  561. """True for content dominated by read_file's ``LINE_NUM|CONTENT`` display (>=60% of
  562. non-empty lines are consecutive numbered lines; a lone ``1|value`` is allowed)."""
  563. if not isinstance(content, str):
  564. return False
  565. lines = [line for line in content.splitlines() if line.strip()]
  566. if len(lines) < 2:
  567. return False
  568. numbered: list[int] = []
  569. for line in lines:
  570. prefix, sep, _rest = line.lstrip().partition("|")
  571. if sep and prefix.isdigit():
  572. numbered.append(int(prefix))
  573. if len(numbered) < 2 or len(numbered) / len(lines) < 0.6:
  574. return False
  575. consecutive_pairs = sum(1 for prev, current in itertools.pairwise(numbered) if current == prev + 1)
  576. return consecutive_pairs >= len(numbered) - 1
  577. def _is_internal_file_tool_content(content: str) -> bool:
  578. """Return True when content is file-tool display text, not intended file bytes."""
  579. return _is_internal_file_status_text(content) or _looks_like_read_file_line_numbered_content(content)