From dc03b4d1547b399bdd587d8eb32c3a99484440b9 Mon Sep 17 00:00:00 2001 From: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> Date: Thu, 12 Nov 2026 21:24:06 +0530 Subject: [PATCH 1/4] Coding agents: Cursor's StrReplace, ApplyPatch and EditNotebook are decided as the edits they are Cursor 3.29.15 names its edit tools StrReplace, Write, Delete, EditNotebook and ApplyPatch (an older prompt: search_replace, write, delete_file, edit_notebook), as Purv-Kabaria found in #755. The Cursor mapping had none of the edit names, so a payload naming them was decided as an unknown tool, a flag: a StrReplace of ~/.cursor/hooks.json ran where a Write of it is held (TK-F009), and one of .env where an Edit of it is denied (TK-D005). StrReplace and search_replace map to Edit, write to Write, delete_file to Edit (as Delete), EditNotebook and edit_notebook to NotebookEdit on their target_notebook. ApplyPatch maps to Edit on every file a patch header names, in any argument, as Cursor reads it (a JSON {"patch": ...} unwrapped, each line trimmed as JavaScript trims). TK-F009 now covers NotebookEdit, the only file-write rule without it. Evals: the packs' new policy hash (no result changed). Cursor's own preToolUse hook (read in 3.26.13 and 3.29.15) sends an edit by any of these tools as a Read and then a Write of the whole file, which was already held; docs/limits.md says so and lists the names it sends that stay unmapped. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> --- docs/coding-agents.md | 2 +- docs/limits.md | 3 +- eval/results/e17_policy_corpus.json | 2 +- eval/results/e21_policy_robustness.json | 4 +- eval/results/e21_robustness.json | 2 +- tests/test_agent_hooks.py | 50 +++++++++++++++++++++++++ tests/test_harness_hooks_v2.py | 42 +++++++++++++++++++++ tests/test_signer_policy.py | 37 ++++++++++++++++++ tracekit/agent_hooks.py | 31 +++++++++++++-- tracekit/policy2/packs/coding.yaml | 2 +- 10 files changed, 164 insertions(+), 11 deletions(-) diff --git a/docs/coding-agents.md b/docs/coding-agents.md index 758a8beb0..de9ac8c27 100644 --- a/docs/coding-agents.md +++ b/docs/coding-agents.md @@ -154,7 +154,7 @@ payloads and Tracekit's installer; not tested in a live Devin session. | Run id | `session_id` | `conversation_id` | `session_id` | `sessionID` | `session_id` | `session_id` | `session_id` | `session_id` | one task (each prompt, from `TaskStart` to `TaskComplete`), keyed on `sessionContext.rootSessionId` (the CLI's session, which `cline --id` resumes; its subagents' calls are in it too), else `taskId` | | Blocking a call | exit 2 + a reason on stderr (and `permissionDecision: deny`); on Windows exit 0 + the JSON deny, since PowerShell turns 2 into 1 and Codex reads the JSON only at 0 | exit 2 + `{"permission": "deny"}` | exit 2 + `{"decision": "deny"}` | the plugin throws before the tool runs when Tracekit blocks the call (exit 2) or the hook can't decide it (any other exit, or Python can't start) | exit 2 + a reason on stderr, stdout empty (a stray stdout line reads as no decision to goose) | exit 2 + a reason on stderr (Qwen Code ignores stdout at exit 2 and sends stderr to the model); nothing on stdout; on Windows the command ends in `; exit $LASTEXITCODE`, since PowerShell turns 2 into 1 | exit 2 + a reason on stderr and `hookSpecificOutput.permissionDecision: "deny"` | exit 2 + a reason on stderr | `{"cancel": true, "errorMessage": ...}` at exit 0 (Cline reads no exit status); a cancel stops the whole task, not only the call | | Tool call ids | from the harness | from the harness | none: paired by tool and arguments, first in first out | `callID` | `tool_call_id`, from the harness | `tool_use_id`, from the harness | none in documented stdin: paired by tool and arguments, first in first out | none in the documented payload: paired by tool and arguments, first in first out | the CLI's `tool_call.id`; the VS Code extension sends none: paired by tool and arguments, first in first out | -| Tool names | `Bash`; `write_stdin` → `Bash` (`command` = the typed `chars`; current Codex sends no hook for it, so what is typed into a running command isn't decided: [limits](limits.md#signer-and-capture)); `apply_patch` → `Edit` (`paths`: every file the patch adds, updates, deletes or moves to, its file headers read as Codex reads them, indented ones too); `apply_patch` run from the shell stays a `Bash` call, which the v2 coding pack holds for a person (`TK-A034`); MCP as `mcp__server__tool` | `Shell` → `Bash`; `Read`, `Write`, `Grep`; `Delete` → `Edit`, so the file rules read it; every path the input names is decided (`file_path`, `path`, `target_file`, `filePath`: Cursor doesn't document which its tools read); `MCP:x` → `mcp__cursor__x` | `run_shell_command` → `Bash`; `read_file` and `read_many_files` → `Read`; `write_file` → `Write`; `replace` → `Edit`; `grep_search` (`search_file_content` in older releases) → `Grep`; `glob`, `list_directory`, `web_fetch`, `google_web_search`; MCP tools, which Gemini CLI names `mcp__`, → `mcp___`; every path a file tool reads is decided, under each release's name for it (`file_path`, `absolute_path`, `dir_path`, `path`, and `read_many_files`' `paths` and `include`); `web_fetch` is decided on every URL its prompt names (`urls`) and on a `url` beside it | `bash` → `Bash`; `read`, `write`, `edit` (path: `filePath`); `apply_patch` (and 1.0's `patch`) → `Edit` (`paths`: every file its headers name, and a path with a `:` also up to it, as OpenCode 1.2 reads it); `batch` (experimental; OpenCode 1.x before 1.4 only: later releases and OpenCode 2 have none) is blocked: OpenCode runs the calls in it without plugin hooks; `glob`, `grep` (path: `path`); `webfetch`, `websearch`, `task`; MCP tools under OpenCode's `_` names, which the policy treats as unknown tools | `shell` → `Bash`; `write` → `Write` (path: `path`); `edit` → `Edit` (path: `path`); `tree` → `LS` (path: `path`); `read_image` → `Read` (path: `source`, not `path`); `__` → `mcp____`; other names pass through unchanged, which the policy treats as unknown tools | `run_shell_command` and `monitor` → `Bash`; `read_file` → `Read` (path: `file_path`, `absolute_path` before 0.13); `write_file` → `Write`; `edit` (and Gemini's `replace`) → `Edit`; `notebook_edit` → `NotebookEdit` (path: `notebook_path`); `grep_search` → `Grep`; `glob`, `list_directory`, `web_fetch`, `web_search`, `todo_write`; `agent` → `Task`; any other tool, MCP tools included, under its own name; file paths as for Gemini CLI; `web_fetch` is decided on its `url` and also on every URL its prompt names (Qwen Code fetches only the `url`) | `Execute` → `Bash`; `Create` → `Write`; `ApplyPatch` → `Edit` (`input`: complete patch; `paths`: all file headers); `FetchUrl` → `WebFetch`; other names, including `mcp__server__tool`, pass through | `exec` → `Bash` (`command` in any case, `\r` read as a line end; denied in the hook with no command, input that isn't an object, or a control character but a tab or line end); `write_to_process` → `Bash` (`command` = its one argument besides `shell_id`, the text it writes, whatever its name: its fields aren't documented; `\r` read as a line end; denied in the hook with any other argument, no text, a control character or a bash history expansion (`!-1`, a `^` starting a line) in the text, or text that sets shell state a later line runs: `fc`, an `alias` definition, a function, `trap`, the `exec` builtin, `PROMPT_COMMAND`, `LD_PRELOAD` …); a name sent twice to any tool, in any case, is denied in the hook; `read` → `Read`; `write` → `Write`; `edit` → `Edit` (each decided on every path under a key ending in `path`, `paths` or `file`, case and `_` ignored, and denied in the hook with none); `apply_patch` → `Edit` (`paths`: all patch file headers and a unified diff's file names; denied in the hook with none); `grep`, `glob`; `webfetch` → `WebFetch` (denied in the hook without a `url`, or with one under another spelling too); `mcp__server__tool` and other names pass through | `run_commands` → `Bash` (`command` for one command, `commands` for several, each decided on its own as Cline runs it in its own shell, a here-doc joined to its delimiter's line; from any shape Cline takes: a list, one command, `{command, args}`, `cmd`); `read_files` → `Read` (`paths`: every file, under `files`, `paths` or `file_paths`); `editor` → `Write` when it sends neither `old_text` nor `insert_line` (it then creates a missing file), else `Edit` (its `path`); `apply_patch` → `Edit` (`paths`: every file the patch names); `fetch_web_content` → `WebFetch` (`urls`: every request's URL); an MCP tool `__` → `mcp____`; a call none of these can be read from is cancelled; the other tools pass under their own names | +| Tool names | `Bash`; `write_stdin` → `Bash` (`command` = the typed `chars`; current Codex sends no hook for it, so what is typed into a running command isn't decided: [limits](limits.md#signer-and-capture)); `apply_patch` → `Edit` (`paths`: every file the patch adds, updates, deletes or moves to, its file headers read as Codex reads them, indented ones too); `apply_patch` run from the shell stays a `Bash` call, which the v2 coding pack holds for a person (`TK-A034`); MCP as `mcp__server__tool` | `Shell` → `Bash`; `Read`, `Write`, `Grep`; `Delete` → `Edit`, so the file rules read it; Cursor's hook sends an edit by any of its tools as a `Read` and then a `Write` of the whole file ([limits](limits.md#signer-and-capture)); the names its transcripts give its edit tools (3.29: `StrReplace`, `ApplyPatch`, `EditNotebook`; an older prompt's `search_replace`, `write`, `delete_file`, `edit_notebook`) → `Edit`, `Edit` (`paths`: every file a patch header names, in any argument), `NotebookEdit` (path: `target_notebook`), `Edit`, `Write`, `Edit`, `NotebookEdit`; every path the input names is decided (`file_path`, `path`, `target_file`, `filePath`, `target_notebook`: Cursor doesn't document which its tools read); `MCP:x` → `mcp__cursor__x`; other names pass through, which the policy treats as unknown tools | `run_shell_command` → `Bash`; `read_file` and `read_many_files` → `Read`; `write_file` → `Write`; `replace` → `Edit`; `grep_search` (`search_file_content` in older releases) → `Grep`; `glob`, `list_directory`, `web_fetch`, `google_web_search`; MCP tools, which Gemini CLI names `mcp__`, → `mcp___`; every path a file tool reads is decided, under each release's name for it (`file_path`, `absolute_path`, `dir_path`, `path`, and `read_many_files`' `paths` and `include`); `web_fetch` is decided on every URL its prompt names (`urls`) and on a `url` beside it | `bash` → `Bash`; `read`, `write`, `edit` (path: `filePath`); `apply_patch` (and 1.0's `patch`) → `Edit` (`paths`: every file its headers name, and a path with a `:` also up to it, as OpenCode 1.2 reads it); `batch` (experimental; OpenCode 1.x before 1.4 only: later releases and OpenCode 2 have none) is blocked: OpenCode runs the calls in it without plugin hooks; `glob`, `grep` (path: `path`); `webfetch`, `websearch`, `task`; MCP tools under OpenCode's `_` names, which the policy treats as unknown tools | `shell` → `Bash`; `write` → `Write` (path: `path`); `edit` → `Edit` (path: `path`); `tree` → `LS` (path: `path`); `read_image` → `Read` (path: `source`, not `path`); `__` → `mcp____`; other names pass through unchanged, which the policy treats as unknown tools | `run_shell_command` and `monitor` → `Bash`; `read_file` → `Read` (path: `file_path`, `absolute_path` before 0.13); `write_file` → `Write`; `edit` (and Gemini's `replace`) → `Edit`; `notebook_edit` → `NotebookEdit` (path: `notebook_path`); `grep_search` → `Grep`; `glob`, `list_directory`, `web_fetch`, `web_search`, `todo_write`; `agent` → `Task`; any other tool, MCP tools included, under its own name; file paths as for Gemini CLI; `web_fetch` is decided on its `url` and also on every URL its prompt names (Qwen Code fetches only the `url`) | `Execute` → `Bash`; `Create` → `Write`; `ApplyPatch` → `Edit` (`input`: complete patch; `paths`: all file headers); `FetchUrl` → `WebFetch`; other names, including `mcp__server__tool`, pass through | `exec` → `Bash` (`command` in any case, `\r` read as a line end; denied in the hook with no command, input that isn't an object, or a control character but a tab or line end); `write_to_process` → `Bash` (`command` = its one argument besides `shell_id`, the text it writes, whatever its name: its fields aren't documented; `\r` read as a line end; denied in the hook with any other argument, no text, a control character or a bash history expansion (`!-1`, a `^` starting a line) in the text, or text that sets shell state a later line runs: `fc`, an `alias` definition, a function, `trap`, the `exec` builtin, `PROMPT_COMMAND`, `LD_PRELOAD` …); a name sent twice to any tool, in any case, is denied in the hook; `read` → `Read`; `write` → `Write`; `edit` → `Edit` (each decided on every path under a key ending in `path`, `paths` or `file`, case and `_` ignored, and denied in the hook with none); `apply_patch` → `Edit` (`paths`: all patch file headers and a unified diff's file names; denied in the hook with none); `grep`, `glob`; `webfetch` → `WebFetch` (denied in the hook without a `url`, or with one under another spelling too); `mcp__server__tool` and other names pass through | `run_commands` → `Bash` (`command` for one command, `commands` for several, each decided on its own as Cline runs it in its own shell, a here-doc joined to its delimiter's line; from any shape Cline takes: a list, one command, `{command, args}`, `cmd`); `read_files` → `Read` (`paths`: every file, under `files`, `paths` or `file_paths`); `editor` → `Write` when it sends neither `old_text` nor `insert_line` (it then creates a missing file), else `Edit` (its `path`); `apply_patch` → `Edit` (`paths`: every file the patch names); `fetch_web_content` → `WebFetch` (`urls`: every request's URL); an MCP tool `__` → `mcp____`; a call none of these can be read from is cancelled; the other tools pass under their own names | What is the same as Claude Code: the policy gate runs before the tool (deny blocks; ask blocks the call until someone approves it from another terminal, then the agent's retry runs: [held calls](#held-calls-approve-then-retry)), events diff --git a/docs/limits.md b/docs/limits.md index 781c9179b..7934c2091 100644 --- a/docs/limits.md +++ b/docs/limits.md @@ -144,6 +144,7 @@ What Tracekit guarantees and doesn't, per deployment, on one page: [guarantees]( | The OpenCode plugin kills a hook still running after 600 seconds and blocks its call, so a hook stuck on a slow or hung signer blocks the call rather than OpenCode. OpenCode 2.0 doesn't load 1.x plugins, so its hooks would stop with no error. | The plugin awaits each hook's process without blocking OpenCode's event loop, so OpenCode keeps streaming and decides parallel calls at once; the hook answers within 540 seconds, a held call's approval wait included, and 600 seconds is the other coding agents' pre-tool timeout. | Check a blocked call's message: `did not answer in 600 s` means the hook hung (`tracekit doctor` checks the signer); pin OpenCode 1.x until Tracekit supports 2.0. | [coding agents](coding-agents.md) | | **(experimental)** Kilo Code support was run with the Kilo CLI 7.8.18 on Linux only: its VS Code extension, Windows and macOS haven't been tried. Kilo's `notebook_execute` (VS Code only, with `experimental.native_notebook_tools`, off by default) is blocked whatever its arguments: the hook refuses it before it runs. | It runs a notebook cell in the live kernel; the cell's code was written by `notebook_edit`, which is decided on its `path` alone, so no command rule ever reads it. | Leave `experimental.native_notebook_tools` off in `kilo.json`; the model then runs code through `bash`, and each command is decided. | [coding agents](coding-agents.md) | | Kilo's own tools that Tracekit doesn't map pass through under their own names, as unknown tools: only the policy's `unknown_tools` (`TK-UNKNOWN-TOOL`) applies, and no rule reads their arguments. Among them: `browser_open` (VS Code; opens its `url` in a browser), `repo_clone` (clones its `repository`, a git URL or `owner/repo`, into Kilo's cache), `kilo_memory_save` (saves a note to Kilo's project memory, which later sessions read back) and `agent_manager` (VS Code; starts sessions). MCP tools reach the plugin under OpenCode's `_` name, so they aren't decided as `mcp:/` and MCP rules don't apply to them (OpenCode's too). A session `agent_manager` starts in worktree mode runs in a new git worktree under the project's `.kilo/worktrees/`; Kilo looks for project config only from there up to that worktree's root, so a `--project` install's `.kilo/plugin/` in the main checkout doesn't reach it (read from Kilo 7.8.18's source; not tried). | Tracekit maps the tools that run a command or read or write a file; these act through Kilo's own services, and Kilo's MCP names don't say where the server name ends. | Set `unknown_tools` to `ask` or `deny` where these tools matter; with Agent Manager worktrees, install without `--project`: the global plugin in `~/.config/kilo` is loaded in every session. | [coding agents](coding-agents.md), [policy v2](policy-v2.md) | +| Cursor's hook names a call by what it does on the computer, not by the model's tool: an edit by `StrReplace`, `ApplyPatch` or `EditNotebook` reaches its `preToolUse` hook as a `Read` and then a `Write` of the whole file, both under the model's call id, so the record shows a `Write` of the file, not the tool. The other names Cursor 3.29.15's hook sends pass through under their own names, as unknown tools (`TK-UNKNOWN-TOOL`: flagged on the dev and coding packs, held on server and strict), and no rule reads their arguments: `Fetch` (a `url`), `List`, `ReadLints`, `WriteShellStdin` (only `shell_id` and the length of the typed text, not the text), `ListMcpResources`, `FetchMcpResource` (with the `download_path` it writes), `ComputerUse`, `RecordScreen` and `XSearch`. | Cursor fires `preToolUse` where a call runs: an edit's file read and its write each fire it, under the names of those operations; the model's tool names are only in its transcripts. Its hooks docs list `Shell`, `Read`, `Write`, `Grep`, `Delete`, `Task` and `MCP:` tools; the other names are read from Cursor 3.29.15's code. | Put an `ask` or `deny` rule of your own on the names your agents shouldn't use; read what an edit changed in the file its `Write` names. | [coding agents](coding-agents.md) | | Kilo's `send_file` uploads a file to Kilo's mobile app but is decided as a `Read` of it, so a secrets file sent that way is only flagged (`TK-F005`) where the same upload from a shell is held. | The upload goes to the user's own Kilo app, and the hook sees one tool name per call. | Hold `send_file` in a rule of your own if your agents shouldn't send files to the app. | [coding agents](coding-agents.md) | | Kilo's `generate_image` given an `image` is decided as a `Read` of that file and of the `path` it writes, so the write rules don't see that `path` (a write under `~/.config/kilo/` or `.git/hooks/` that a `Write` there would hold or deny); Kilo gives the written file an image extension (`.png`, `.jpg` or `.jpeg`). | The hook decides each call as one tool, and the file it reads and sends off is the larger risk. | Hold `generate_image` in a rule of your own if image writes outside the project matter to you. | [coding agents](coding-agents.md) | | Factory Droid's documented hook stdin gives a tool call no id. Two identical calls in flight are paired first in first out, so their results cannot be distinguished if they complete in another order. An allowed call with no PostToolUse (declined in Droid's permission prompt, blocked by another hook, or failed; Droid has no PostToolUseFailure) stays queued, so the next identical call's result can be paired to it and the call that ran closes as an error at session end. | Only the tool name and arguments connect Droid's PreToolUse and PostToolUse events. | Avoid concurrent identical calls when their result attribution matters. Blocked calls leave the queue so a later allowed call does not inherit their id. | [coding agents](coding-agents.md) | @@ -180,7 +181,7 @@ What Tracekit guarantees and doesn't, per deployment, on one page: [guarantees]( | On the dev signer, an app's own tool named `Agent`, `Task`, `SendMessage`, `SubagentHandback` or `TodoWrite` (an SDK agent's, not Claude Code's) is read as a coding agent's message to its own agents (class `harness`): the file names in its arguments aren't read by `TK-S004` or `TK-F005`, a `SendMessage` is flagged as one, and an `Agent` or `Task` whose arguments hold `"isolation":"remote"` is held. | The policy maps tools by name; the dev signer serves coding agents' hooks and SDK apps alike. | Name your app's tools otherwise, or map them in a policy of your own (`tools:`), which wins over the pack's. | [policy](policy-v2.md#packs-shipped) | | `TK-A056` reads a remote's push or mirror setting only when the push line gives it (`git -c remote.origin.push=HEAD:main push origin feature` is held). One set earlier with `git config remote.origin.push …` (`TK-A013` doesn't hold that), in the repository's config or in a global one, sends a later `git push origin feature` where it says, to main too, and the push stays flagged. | The push line is all a rule reads; the config file isn't read when a call is decided. | Protect the default branch on the remote; review a change to `remote.*.push` in a repository's config. | [policy](policy-v2.md#packs-shipped) | | A single message, email or post sent outside isn't held: `gh issue create`, `gh pr comment`, one email or a chat MCP tool's message is recorded (an MCP call flagged, `TK-F006`); a secret in it is denied (`TK-S002`), and so are mass email and a whole-channel notice (`TK-M003`, `TK-M004`, held). | No rule reads what a single message says. | Add an `ask` rule of your own for the messaging tools your agents have. | [policy](policy-v2.md#packs-shipped) | -| An agent's edit of its own harness's settings, hooks, MCP servers, skills or slash commands (`.claude/settings.json`, `~/.claude.json`, `.claude/skills/` and `.claude/commands/`, whose `!` lines run commands, `~/.gemini/settings.json`, `.codex/`, `~/.cursor/hooks.json` and `mcp.json`, OpenCode's `.opencode/`, `opencode.json` and, from the shell, `~/.config/opencode` or `$XDG_CONFIG_HOME/opencode` (the shell rule matches the variable's name; a file tool gets the expanded path, so its write is denied only at `~/.config/opencode`, `TK-D009`), Qwen Code's `.qwen/` and `~/.qwen/settings.json`, Factory Droid's `.factory/`, Devin's `.devin/`, `~/.config/devin` and, on Windows, `AppData\Roaming\devin` (the folder `%APPDATA%` names: a path written through the variable isn't matched), Antigravity CLI's `~/.gemini/config/hooks.json` and `.agents/hooks.json`, goose's `.agents/plugins/` and `~/.config/goose`, Crush's `crush.json`, `.crush.json`, `crushrc`, `.crushrc` and `~/.config/crush`, PowerShell's profiles (a `*profile.ps1` in `Documents/WindowsPowerShell/` or `Documents/PowerShell/`, OneDrive's Documents too under its localized name (`OneDrive - Contoso/Dokumente/`), pwsh's `~/.config/powershell/` on Linux and macOS, or the `$PSHOME` of Windows PowerShell (`System32/WindowsPowerShell/v1.0/`) or PowerShell 7 (`PowerShell/7/`, `PowerShell/7-preview/`), and `$PROFILE` or `$global:PROFILE` by name from the shell), which run before a hook PowerShell starts without `-NoProfile`, by a file-editing tool (Write, Edit or MultiEdit) or a recognized shell write) is held (`TK-F009`, `TK-F015`, since #604); one the rules don't read (below) runs, and once it turns the sandbox off, `TK-A003`, `TK-A004` and `TK-A014` have nothing to hold: later commands run outside it with no escape-hatch argument. The file rule reads the normalized path, and the shell rule reads `WRITE_TARGET:` and `DELETE_TARGET:` effects (redirects, `tee`, `cp`, `mv`, `sed -i`, `rm`, `find -delete`, `git rm`, awk's `print > "file"`, …). Both also match casefolded paths. Reads and content that merely names these paths do not match. Not flagged: Cursor's rules (`.cursor/rules/`), Windsurf's and VS Code's settings, a Claude Code config folder moved elsewhere (`CLAUDE_CONFIG_DIR`, `~/.config/claude-code`) and instruction files agents edit in ordinary work (`AGENTS.md`, `CLAUDE.md`); `TK-F016`/`TK-F017` read an `ANTHROPIC_…BASE_URL` name only when it is written in one piece (not split by a line continuation), and not a proxy variable (`HTTPS_PROXY`). A file inside one of Claude Code's worktrees (`.claude/worktrees//…`) is read as it is in the worktree: an ordinary file there isn't flagged, the worktree's own `.claude/`, `.codex/`, `.mcp.json` and the rest are, and so is a worktree named as a dot folder, the worktree itself, and a shell target with a `..`, or an expansion or glob that can make one (`$D`, `{..,a}`, `.*`), among its first 32 parts after the worktree, or more parts than that. A link made in a worktree that points out of it (`ln -s ../.. .claude/worktrees/x/up`, then a write to `up/settings.json`) isn't followed, as a link made anywhere else isn't. `ANTHROPIC_BASE_URL` (where the agent's model calls go) is flagged wherever a call names it, in any case (Windows reads a variable's name so): in a Write, Edit or MultiEdit call's arguments (`TK-F016`; a NotebookEdit cell isn't read) and on a shell line from any shell tool, an assignment prefix (`ANTHROPIC_BASE_URL=x claude`) and the text a heredoc or `echo` writes included (`TK-F017`). A mention is flagged as well as a setting, so a grep, a note or a comment that names the variable is flagged too: noisy by design, and only a flag. Under `QWEN_HOME`, the shell rule matches only the variable's name (`$QWEN_HOME/settings.json`); a file tool's write to the directory it names is not matched. A write through any other variable, a script or another program (`curl -o`, `wget -O`, `touch`, `rsync`, `git restore`, an editor, an interpreter one-liner) is not matched, nor is a PowerShell cmdlet that writes or deletes a profile (`Add-Content`, `Set-Content`, `Out-File`, `Remove-Item`) or a profile in a Documents folder redirected elsewhere (a path without `Documents` or `OneDrive`). | The rules cover every file under those directories (skills, commands) but Claude Code's memory notes (`.claude/projects//memory/*.md`, the agent's own notes, not settings) and the ordinary files of its worktrees (a checkout of the project, not settings); agents edit those files in normal work. The rest are held: on one developer's week of Tracekit work, 19 calls in 7 days, 13 of them test fixtures written in scratch folders or a worktree's removal. | Approve a held settings change only when you meant it; keep the sandbox's settings where the agent can't write (managed settings, a read-only mount); add an `ask` rule of your own for the settings files your agents never need to touch. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#what-tracekit-sees-and-doesnt), [Gemini CLI's sandbox](integrations/gemini-sandbox.md) | +| An agent's edit of its own harness's settings, hooks, MCP servers, skills or slash commands (`.claude/settings.json`, `~/.claude.json`, `.claude/skills/` and `.claude/commands/`, whose `!` lines run commands, `~/.gemini/settings.json`, `.codex/`, `~/.cursor/hooks.json` and `mcp.json`, OpenCode's `.opencode/`, `opencode.json` and, from the shell, `~/.config/opencode` or `$XDG_CONFIG_HOME/opencode` (the shell rule matches the variable's name; a file tool gets the expanded path, so its write is denied only at `~/.config/opencode`, `TK-D009`), Qwen Code's `.qwen/` and `~/.qwen/settings.json`, Factory Droid's `.factory/`, Devin's `.devin/`, `~/.config/devin` and, on Windows, `AppData\Roaming\devin` (the folder `%APPDATA%` names: a path written through the variable isn't matched), Antigravity CLI's `~/.gemini/config/hooks.json` and `.agents/hooks.json`, goose's `.agents/plugins/` and `~/.config/goose`, Crush's `crush.json`, `.crush.json`, `crushrc`, `.crushrc` and `~/.config/crush`, PowerShell's profiles (a `*profile.ps1` in `Documents/WindowsPowerShell/` or `Documents/PowerShell/`, OneDrive's Documents too under its localized name (`OneDrive - Contoso/Dokumente/`), pwsh's `~/.config/powershell/` on Linux and macOS, or the `$PSHOME` of Windows PowerShell (`System32/WindowsPowerShell/v1.0/`) or PowerShell 7 (`PowerShell/7/`, `PowerShell/7-preview/`), and `$PROFILE` or `$global:PROFILE` by name from the shell), which run before a hook PowerShell starts without `-NoProfile`, by a file-editing tool (Write, Edit, MultiEdit or NotebookEdit) or a recognized shell write) is held (`TK-F009`, `TK-F015`, since #604); one the rules don't read (below) runs, and once it turns the sandbox off, `TK-A003`, `TK-A004` and `TK-A014` have nothing to hold: later commands run outside it with no escape-hatch argument. The file rule reads the normalized path, and the shell rule reads `WRITE_TARGET:` and `DELETE_TARGET:` effects (redirects, `tee`, `cp`, `mv`, `sed -i`, `rm`, `find -delete`, `git rm`, awk's `print > "file"`, …). Both also match casefolded paths. Reads and content that merely names these paths do not match. Not flagged: Cursor's rules (`.cursor/rules/`), Windsurf's and VS Code's settings, a Claude Code config folder moved elsewhere (`CLAUDE_CONFIG_DIR`, `~/.config/claude-code`) and instruction files agents edit in ordinary work (`AGENTS.md`, `CLAUDE.md`); `TK-F016`/`TK-F017` read an `ANTHROPIC_…BASE_URL` name only when it is written in one piece (not split by a line continuation), and not a proxy variable (`HTTPS_PROXY`). A file inside one of Claude Code's worktrees (`.claude/worktrees//…`) is read as it is in the worktree: an ordinary file there isn't flagged, the worktree's own `.claude/`, `.codex/`, `.mcp.json` and the rest are, and so is a worktree named as a dot folder, the worktree itself, and a shell target with a `..`, or an expansion or glob that can make one (`$D`, `{..,a}`, `.*`), among its first 32 parts after the worktree, or more parts than that. A link made in a worktree that points out of it (`ln -s ../.. .claude/worktrees/x/up`, then a write to `up/settings.json`) isn't followed, as a link made anywhere else isn't. `ANTHROPIC_BASE_URL` (where the agent's model calls go) is flagged wherever a call names it, in any case (Windows reads a variable's name so): in a Write, Edit or MultiEdit call's arguments (`TK-F016`; a NotebookEdit cell isn't read) and on a shell line from any shell tool, an assignment prefix (`ANTHROPIC_BASE_URL=x claude`) and the text a heredoc or `echo` writes included (`TK-F017`). A mention is flagged as well as a setting, so a grep, a note or a comment that names the variable is flagged too: noisy by design, and only a flag. Under `QWEN_HOME`, the shell rule matches only the variable's name (`$QWEN_HOME/settings.json`); a file tool's write to the directory it names is not matched. A write through any other variable, a script or another program (`curl -o`, `wget -O`, `touch`, `rsync`, `git restore`, an editor, an interpreter one-liner) is not matched, nor is a PowerShell cmdlet that writes or deletes a profile (`Add-Content`, `Set-Content`, `Out-File`, `Remove-Item`) or a profile in a Documents folder redirected elsewhere (a path without `Documents` or `OneDrive`). | The rules cover every file under those directories (skills, commands) but Claude Code's memory notes (`.claude/projects//memory/*.md`, the agent's own notes, not settings) and the ordinary files of its worktrees (a checkout of the project, not settings); agents edit those files in normal work. The rest are held: on one developer's week of Tracekit work, 19 calls in 7 days, 13 of them test fixtures written in scratch folders or a worktree's removal. | Approve a held settings change only when you meant it; keep the sandbox's settings where the agent can't write (managed settings, a read-only mount); add an `ask` rule of your own for the settings files your agents never need to touch. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#what-tracekit-sees-and-doesnt), [Gemini CLI's sandbox](integrations/gemini-sandbox.md) | | `TK-A003` holds a call only when it carries `dangerouslyDisableSandbox: true`. Commands matching `excludedCommands`, hooks and MCP servers run outside the sandbox without it. | Claude Code marks only the unsandboxed retry; the rest are outside the sandbox by configuration. | Keep `excludedCommands` short; the policy still decides each excluded command and MCP tool call. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#what-tracekit-sees-and-doesnt) | | `TK-A014` holds a call whose `allowed_domains` names a host; it doesn't see hosts opened by the sandbox's own settings (`network.allowedDomains`), and it can't tell which of the listed hosts a command then reached. **(1.5.1)** It reads only Bash, PowerShell and Monitor calls, the tools Claude Code documents as opening hosts this way (WebSearch's `allowed_domains` only narrows results): a new tool that opens hosts with `allowed_domains` isn't held until the pack names it. | The hook sees the call's arguments, not the sandbox's settings or its proxy's traffic. | Keep the hosts a project always needs in `network.allowedDomains` (a person edits the settings) and approve the rest one command at a time. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#per-command-allowed-domains-tk-a014) | | A tool name a framework rewrote (CrewAI's `bash` for `Bash`, `multi_edit` for `MultiEdit`) is also decided as the tool `tools:` lists with that spelling (case, accents, spaces and punctuation ignored), as each one when two listed names share it (the server pack's `bash` and `Bash`), and its results are untrusted when that tool's are; an MCP tool's bare name is read the same way. Nothing else reads it so: a rule whose `tool:` names a tool `tools:` doesn't list (`tool: RefundTool`, which CrewAI sends as `refund_tool`) doesn't take it, and constraints, the egress observer's host, detection's sum limits and a fail mode in an outage go by the class of the name as sent (`unknown`); an agent approver can't answer it, as the policy doesn't name it exactly. A name with no ASCII letter or digit, or a name over 64 characters (CrewAI cuts it and adds a hash) is decided only as sent. Each name a call is decided as gets the fallback regex engine's time budget of its own, so on a crafted 64 KiB argument a renamed tool's decision can take a second per name (re2 is unaffected). | A `tool:` pattern can't be spelled backwards; deciding both names and keeping the stricter decision never decides a call less strictly than before. | List each tool under its declared name in `tools:` (`RefundTool: app`), or write a rule's `tool:` as the framework sends it; keep the `default` fail mode closed, as it ships. | [policy](policy-v2.md#classes-and-fields), [CrewAI](integrations/crewai.md) | diff --git a/eval/results/e17_policy_corpus.json b/eval/results/e17_policy_corpus.json index 558d9fa0f..7afb65c7c 100644 --- a/eval/results/e17_policy_corpus.json +++ b/eval/results/e17_policy_corpus.json @@ -1,5 +1,5 @@ { - "policy_hash": "sha256:9d266fdb9e6ea0d47f40fa38a7422ec77fa6cdbcc1b0fbc13a257ee239b3c250", + "policy_hash": "sha256:61e6357013eed239e70619feb253543b654931c8a003ed756b92e48e17276a43", "engines": [ "re2@1.1.20251105", "regex@2026.9.29" diff --git a/eval/results/e21_policy_robustness.json b/eval/results/e21_policy_robustness.json index 2dcc74c28..384e50d21 100644 --- a/eval/results/e21_policy_robustness.json +++ b/eval/results/e21_policy_robustness.json @@ -10,7 +10,7 @@ "profiles": { "default": { "pack": "server.yaml", - "policy_hash": "sha256:9d266fdb9e6ea0d47f40fa38a7422ec77fa6cdbcc1b0fbc13a257ee239b3c250", + "policy_hash": "sha256:61e6357013eed239e70619feb253543b654931c8a003ed756b92e48e17276a43", "heldout": { "recall": 0.6071428571428571, "deny_recall": 0.2761904761904762, @@ -2708,7 +2708,7 @@ }, "strict": { "pack": "strict.yaml", - "policy_hash": "sha256:c3d8b0c6a581d6dbfc6f11d1fa95aca3c8c7b63af659bebea6e27f3bd70e4966", + "policy_hash": "sha256:00a117e591024d5e2ca2466530959850034c99cb9d5799ae340e4aabf54133d8", "heldout": { "recall": 0.6785714285714286, "deny_recall": 0.36666666666666664, diff --git a/eval/results/e21_robustness.json b/eval/results/e21_robustness.json index 4ab1c4078..ca410efdd 100644 --- a/eval/results/e21_robustness.json +++ b/eval/results/e21_robustness.json @@ -4475,7 +4475,7 @@ } } }, - "policy_hash": "sha256:9d266fdb9e6ea0d47f40fa38a7422ec77fa6cdbcc1b0fbc13a257ee239b3c250", + "policy_hash": "sha256:61e6357013eed239e70619feb253543b654931c8a003ed756b92e48e17276a43", "regressions": [], "rewrite_missed": [], "rewritten_cases": 511, diff --git a/tests/test_agent_hooks.py b/tests/test_agent_hooks.py index 05ac88b6e..9c1ebe071 100644 --- a/tests/test_agent_hooks.py +++ b/tests/test_agent_hooks.py @@ -161,6 +161,25 @@ def test_cursor(self): flags = [e["data"] for e in evs if e["type"] == "policy.decision"] self.assertEqual([f["decision"] for f in flags], ["allow", "flag", "deny"]) + def test_cursor_edit_tools_are_decided_as_edits(self): + # the names Cursor's transcripts give its edits (#755) were unknown tools: a StrReplace of .env was allowed + base = {"conversation_id": "cu-edit", "hook_event_name": "preToolUse", "cwd": self.d} + app, env = os.path.join(self.d, "app.py"), os.path.join(self.d, ".env") + code, out, err = self.hook("cursor", {**base, "tool_name": "StrReplace", "tool_use_id": "e0", + "tool_input": {"path": env, "old_string": "A=1", "new_string": "A=2"}}) + self.assertEqual((code, json.loads(out)["permission"]), (2, "deny"), err) + for i, (name, ti) in enumerate(( + ("StrReplace", {"path": app, "old_string": "a", "new_string": "b"}), + ("ApplyPatch", {"patch": f"*** Begin Patch\n*** Update File: {app}\n@@\n-a\n+b\n*** End Patch\n"}), + ("EditNotebook", {"target_notebook": os.path.join(self.d, "a.ipynb"), "cell_idx": 0, + "is_new_cell": True, "cell_language": "python", "old_string": "", "new_string": "1"})), 1): + code, out, err = self.hook("cursor", {**base, "tool_name": name, "tool_use_id": f"e{i}", "tool_input": ti}) + self.assertEqual((code, json.loads(out)), (0, {"permission": "allow"}), err) + evs = self.events("cu-edit") + self.assertEqual([e["data"]["name"] for e in evs if e["type"] == "tool.call"], ["Edit", "Edit", "Edit", "NotebookEdit"]) + self.assertEqual([e["data"]["decision"] for e in evs if e["type"] == "policy.decision"], + ["deny", "allow", "allow", "allow"]) + def test_qwen(self): base = {"session_id": "qw-1", "cwd": self.d, "model": "qwen3-coder-plus", "transcript_path": None, "permission_mode": "default", "timestamp": "2026-10-25T00:00:00Z"} @@ -1015,6 +1034,37 @@ def test_a_failed_result_is_a_post_tool_failure(self): self.assertIsNone(agent_hooks.normalise("devin", {"session_id": "s", "hook_event_name": ev}), ev) +class CursorTools(unittest.TestCase): + """Cursor's file tools under the names its transcripts give them (3.29.15: StrReplace, Write, Delete, EditNotebook, + ApplyPatch; an older prompt's search_replace, write, delete_file and edit_notebook; Purv-Kabaria in #755) are + decided by both policies on the file each tool reads, whatever other path key the model sent beside it.""" + + def test_each_is_decided_on_the_file_its_tool_reads(self): + from tracekit import policy + v1, v2 = policy.load(policy.DEFAULT_POLICY)[0], load_policy() + env, decoy = "/w/.env", "/w/notes.txt" + patch = f"*** Begin Patch\n*** Add File: {decoy}\n+hi\n*** Update File: {env}\n@@\n-A=1\n+A=2\n*** End Patch\n" + for form, tool in ((("StrReplace", {"path": env, "old_string": "A=1", "new_string": "A=2"}), "Edit"), + (("StrReplace", {"file_path": decoy, "path": env, "old_string": "a", "new_string": "b"}), "Edit"), + (("search_replace", {"file_path": env, "old_string": "A=1", "new_string": "A=2"}), "Edit"), + (("write", {"file_path": env, "contents": "A=1"}), "Write"), + (("delete_file", {"target_file": env}), "Edit"), + (("EditNotebook", {"target_notebook": env, "file_path": decoy, "notebook_path": decoy}), + "NotebookEdit"), + (("edit_notebook", {"target_notebook": env}), "NotebookEdit"), + (("ApplyPatch", {"patch": patch, "path": decoy, "file_path": decoy}), "Edit"), + (("ApplyPatch", patch), "Edit")): + with self.subTest(form=form): + mapped, ti = agent_hooks.tool("cursor", *form) + self.assertEqual(mapped, tool) + d = policy.evaluate(v1, mapped, ti, "/w") + self.assertEqual((d["decision"], "TK-D005" in d["rule_ids"]), ("deny", True), d) + d = v2.decide(mapped, ti) + self.assertEqual((d["verdict"], "TK-D005" in d["rule_ids"]), ("deny", True), d) + _, ti = agent_hooks.tool("cursor", "ApplyPatch", {"patch": patch}) + self.assertEqual((ti["file_path"], ti["paths"]), (decoy, [decoy, env])) + + class CodexPatchHeaders(unittest.TestCase): """Codex (codex-rs/apply-patch) reads a hunk header after Begin Patch, an Add or a Delete hunk from the line with its Unicode whitespace trimmed, so an indented header names a file Codex writes.""" diff --git a/tests/test_harness_hooks_v2.py b/tests/test_harness_hooks_v2.py index 7c31c0e34..2ecb05f8d 100644 --- a/tests/test_harness_hooks_v2.py +++ b/tests/test_harness_hooks_v2.py @@ -542,6 +542,48 @@ def test_a_cursor_call_is_decided_on_every_path_its_input_names(self): self.assertEqual((code, json.loads(out)["permission"]), (2, "deny")) self.assertIn("TK-D005", err) + def test_cursor_edit_tools_are_decided_as_the_edits_they_are(self): + # Cursor's transcripts name its edits StrReplace, ApplyPatch and EditNotebook (an older prompt's search_replace, + # write, delete_file and edit_notebook; Purv-Kabaria, #755): an edit of its hooks under those names was a flag + hooks, sid = "/home/u/.cursor/hooks.json", "c-edit" + + def call(i, name, ti, ev="preToolUse"): + return self.hook("cursor", {"conversation_id": sid, "hook_event_name": ev, "tool_name": name, + "tool_use_id": f"e{i}", "tool_input": ti, "cwd": "/w"}) + # what Cursor 3.29's hook sends for an edit by any of its tools: a Read, then a Write of the whole file, both + # under the model's call id + self.assertEqual(call(0, "Read", {"file_path": hooks})[:2], (0, json.dumps({"permission": "allow"}))) + call(0, "Read", {"file_path": hooks}, "postToolUse") + patch = f"*** Begin Patch\n*** Update File: {hooks}\n@@\n-a\n+b\n*** End Patch\n" + cell = {"cell_idx": 0, "is_new_cell": False, "cell_language": "python", "old_string": "a", "new_string": "b"} + for i, (name, ti) in enumerate((("Write", {"file_path": hooks, "content": "{}"}), + ("StrReplace", {"path": hooks, "old_string": "a", "new_string": "b"}), + ("search_replace", {"file_path": hooks, "old_string": "a", "new_string": "b"}), + ("write", {"file_path": hooks, "contents": "{}"}), + ("ApplyPatch", {"patch": patch}), ("ApplyPatch", patch), + ("EditNotebook", {"target_notebook": hooks, **cell}), + ("edit_notebook", {"target_notebook": hooks, **cell}))): + with self.subTest(tool=name, input=ti): + code, out, err = call(i, name, ti) + self.assertEqual((code, json.loads(out)["permission"]), (2, "deny"), err) + self.assertIn("TK-F009", err) + # an ordinary edit is decided as an Edit, not as an unknown tool + code, out, err = call(20, "StrReplace", {"path": "/w/src/app.py", "old_string": "a", "new_string": "b"}) + self.assertEqual((code, json.loads(out)), (0, {"permission": "allow"}), err) + # a delete, under either name, as strictly as before + for i, (name, key) in enumerate((("Delete", "path"), ("delete_file", "target_file")), 21): + code, out, err = call(i, name, {key: "/w/.env"}) + self.assertEqual((code, json.loads(out)["permission"]), (2, "deny"), name) + self.assertIn("TK-D005", err) + st, c = claude_code._load(claude_code._state(sid)), Client() + self.addCleanup(c.close) + evs = c.call("read", {"run_id": st["run_id"], "run_token": st["run_token"], "limit": 100})["events"] + decided = {e["data"]["tool_use_id"]: (e["data"]["tool"], e["data"]["rule_ids"]) for e in evs + if e["type"] == "policy.decision"} + self.assertEqual(decided["e20"], ("Edit", [])) + self.assertEqual([decided[f"e{i}"][0] for i in range(1, 8)], + ["Edit", "Edit", "Write", "Edit", "Edit", "NotebookEdit", "NotebookEdit"]) + def test_a_devin_file_call_is_decided_on_every_path_its_input_names(self): # the review of #576: the signer decided only the first path key, so a decoy file_path beside the path Devin's # tool reads let a write of .env through diff --git a/tests/test_signer_policy.py b/tests/test_signer_policy.py index 9d510c20f..0337e709a 100644 --- a/tests/test_signer_policy.py +++ b/tests/test_signer_policy.py @@ -2280,6 +2280,43 @@ def test_each_harness_config_an_agent_could_turn_its_sandbox_or_hooks_off_in_is_ with self.subTest(args=args): self.assertIn("TK-F015" if tool == "Bash" else "TK-F009", self.e.decide(tool, args)["rule_ids"]) + def test_cursor_edit_tools_are_decided_as_the_edits_they_are(self): + # Cursor's transcripts name its edits StrReplace, ApplyPatch and EditNotebook (an older prompt's search_replace, + # write, delete_file and edit_notebook; found by Purv-Kabaria in #755): they were decided as unknown tools, a + # flag, where an Edit or Write of the same file is held or denied + from tracekit import agent_hooks + hooks, env, src = "/home/u/.cursor/hooks.json", "/w/.env", "/w/src/app.py" + for path in (hooks, env, src): + patch = f"*** Begin Patch\n*** Update File: {path}\n@@\n-a\n+b\n*** End Patch\n" + edit, write = ("Edit", {"file_path": path, "old_string": "a", "new_string": "b"}), ( + "Write", {"file_path": path, "content": "{}"}) + cell = {"cell_idx": 0, "is_new_cell": False, "cell_language": "python", "old_string": "a", "new_string": "b"} + cases = ((("StrReplace", {"path": path, "old_string": "a", "new_string": "b"}), edit), + (("search_replace", {"file_path": path, "old_string": "a", "new_string": "b"}), edit), + (("Write", {"path": path, "contents": "{}"}), write), + (("write", {"file_path": path, "contents": "{}"}), write), + (("Delete", {"path": path}), ("Edit", {"file_path": path})), + (("delete_file", {"target_file": path}), ("Edit", {"file_path": path})), + (("ApplyPatch", {"patch": patch}), ("Edit", {"file_path": path})), + # Cursor unwraps a JSON {"patch": ...} and reads a header from the line trimmed as JavaScript trims + (("ApplyPatch", {"patch": json.dumps({"patch": patch})}), ("Edit", {"file_path": path})), + (("ApplyPatch", {"patch": patch.replace("*** Update", " *** Update"), "path": "/w/a.txt"}), + ("Edit", {"file_path": path})), + (("EditNotebook", {"target_notebook": path, **cell}), ("NotebookEdit", {"notebook_path": path})), + (("edit_notebook", {"target_notebook": path, **cell}), ("NotebookEdit", {"notebook_path": path}))) + for pack, engine, e in self.every_pack(): + for form, single in cases: + with self.subTest(pack=pack, engine=engine, form=form): + got, want = e.decide(*agent_hooks.tool("cursor", *form)), e.decide(*single) + self.assertEqual((got["verdict"], got["rule_ids"]), (want["verdict"], want["rule_ids"])) + if path == hooks: # held as a Write of it is + self.assertEqual((got["verdict"], "TK-F009" in got["rule_ids"]), + (e.decide(*write)["verdict"], True)) + elif path == env: + self.assertEqual((got["verdict"], "TK-D005" in got["rule_ids"]), ("deny", True)) + else: + self.assertNotIn("TK-UNKNOWN-TOOL", got["rule_ids"]) + def test_opencode_config_changes_are_flagged_but_reads_and_near_names_are_allowed(self): for tool, path in (("Write", "/repo/.opencode/commands/deploy.md"), ("Write", "/repo/.opencode/plugin/tracekit.ts"), diff --git a/tracekit/agent_hooks.py b/tracekit/agent_hooks.py index 425f5cba2..65eb0b0d7 100644 --- a/tracekit/agent_hooks.py +++ b/tracekit/agent_hooks.py @@ -24,7 +24,10 @@ harness -> Tracekit Codex Bash, write_stdin, apply_patch, mcp__s__t Bash, Bash (command = chars), Edit (paths: every file the patch adds, updates, deletes or moves to), mcp__s__t - Cursor Shell, Read, Write, Grep, Delete, MCP:t Bash, Read, Write, Grep, Edit, mcp__cursor__t + Cursor Shell, Read, Write, Grep, Delete, MCP:t Bash, Read, Write, Grep, Edit, mcp__cursor__t (its hook sends an + edit as a Write of the file); its transcripts' StrReplace, ApplyPatch, EditNotebook, search_replace, write, + delete_file, edit_notebook -> Edit, Edit (all patch file headers in paths), NotebookEdit, Edit, Write, Edit, + NotebookEdit Gemini run_shell_command, read_file, read_many_files, write_file, replace, glob, search_file_content, list_directory, web_fetch, google_web_search -> Bash, Read, Read, Write, Edit, Glob, Grep, LS, WebFetch, WebSearch (every path a file tool reads, under @@ -105,9 +108,14 @@ # a URL in Gemini CLI's web_fetch prompt: its scheme in any case (WHATWG URL parsing), up to a character JavaScript's # \s matches (the prompt is split on them) WEB_FETCH_URL = re.compile(r"https?://[^\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+", re.I) -# a Delete is an Edit, as a Codex patch's Delete File is: the file rules (a credentials file, the transcripts) read it -CURSOR_TOOLS = {"Shell": "Bash", "Read": "Read", "Write": "Write", "Grep": "Grep", "Delete": "Edit", "Task": "Task", "Edit": "Edit"} -CURSOR_PATH_ARGS = ("file_path", "path", "target_file", "filePath") +# Cursor's hooks name a call by what it does on the computer: an edit by any of its tools reaches preToolUse as a Read and +# then a Write of the whole file (file_path, content). Its transcripts name the model's tools (Cursor 3.29): StrReplace, +# Write, Delete, EditNotebook, ApplyPatch, and an older prompt's search_replace, write, delete_file and edit_notebook. +# A Delete is an Edit, as a Codex patch's Delete File is: the file rules (a credentials file, the transcripts) read it +CURSOR_TOOLS = {"Shell": "Bash", "Read": "Read", "Write": "Write", "Grep": "Grep", "Delete": "Edit", "Task": "Task", + "Edit": "Edit", "StrReplace": "Edit", "search_replace": "Edit", "write": "Write", "delete_file": "Edit", + "EditNotebook": "NotebookEdit", "edit_notebook": "NotebookEdit"} +CURSOR_PATH_ARGS = ("file_path", "path", "target_file", "filePath", "target_notebook") OPENCODE_TOOLS = {"bash": "Bash", "read": "Read", "write": "Write", "edit": "Edit", "apply_patch": "Edit", "patch": "Edit", "glob": "Glob", "grep": "Grep", "webfetch": "WebFetch", "websearch": "WebSearch", "task": "Task", "todowrite": "TodoWrite"} @@ -369,6 +377,21 @@ def tool(harness, name, ti): if harness == "cursor": if name.startswith("MCP:"): return "mcp__cursor__" + re.sub(r"[^A-Za-z0-9_-]+", "_", name[4:]), ti + if name == "ApplyPatch": # every file a patch header names, in whichever argument holds it, as Cursor reads it: + # a {"patch": ...} in JSON unwrapped, each line trimmed as JavaScript trims it + texts = list(_strings(ti)) + for s in texts[:]: + with contextlib.suppress(ValueError, RecursionError): + j = json.loads(JS_TRIM.sub("", s)) + if isinstance(j, dict) and list(j) == ["patch"] and isinstance(j["patch"], str): + texts.append(j["patch"]) + lines = "\n".join(JS_TRIM.sub("", x) for x in "\n".join(texts).split("\n")) + ti["paths"] = files = [JS_TRIM.sub("", f) for f in PATCH_FILE.findall(lines)] + ti["file_path"] = files[0] if files else None + return "Edit", ti + if name in ("EditNotebook", "edit_notebook"): # it reads target_notebook; v1 decides a NotebookEdit on its + # file_path and notebook_path + ti["file_path"] = ti["notebook_path"] = ti.get("target_notebook") for k in CURSOR_PATH_ARGS[1:]: if k in ti and "file_path" not in ti: ti["file_path"] = ti[k] diff --git a/tracekit/policy2/packs/coding.yaml b/tracekit/policy2/packs/coding.yaml index f8b69d7cb..b29a97a6d 100644 --- a/tracekit/policy2/packs/coding.yaml +++ b/tracekit/policy2/packs/coding.yaml @@ -878,7 +878,7 @@ ask: # --- the agent harness's settings: held, as changing the guardrails (#604) - id: TK-F009 class: fs - tool: Write|Edit|MultiEdit + tool: Write|Edit|MultiEdit|NotebookEdit field: path # Only the normalized path, including its casefolded form, not the file's content. Antigravity CLI's project hooks # are .agents/hooks.json and goose's plugins are under .agents/plugins/ (the folder's skills/ is ordinary work); From e4227b26ef3b32f788d7e2bb38d60ffd189d3348 Mon Sep 17 00:00:00 2001 From: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:16:12 +0530 Subject: [PATCH 2/4] Cursor: an edit naming no file stays an unknown tool; \r line ends; linear trim; TK-F016 reads NotebookEdit From the review of #767: - A Cursor edit Tracekit can't read a file from (an ApplyPatch with no file header, an empty or non-string patch, a StrReplace, search_replace, write, delete_file, EditNotebook or edit_notebook without a string in the argument its tool reads its file from) was mapped to an Edit of no file and allowed. It now keeps its own name, an unknown tool, decided exactly as on main. - ApplyPatch reads \r and \r\n as line ends, as Cursor does: a CR-only patch of ~/.cursor/hooks.json was decided on no file. It is held. - JavaScript's trim() is str.strip over JavaScript's whitespace (JS_SPACE), not a regex that took 4.65 s on a line of 40,000 spaces; OpenCode's and Cline's patch and here-doc readers used the same regex. JSON is tried only on text starting with {. - TK-F016 also reads NotebookEdit, as TK-F009 now does. Coding pack 2026.11-v2-83 (v2-82 is #761's); eval results get the new policy hashes, no result changed. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> --- docs/coding-agents.md | 2 +- docs/limits.md | 2 +- eval/results/e17_policy_corpus.json | 2 +- eval/results/e21_policy_robustness.json | 4 +- eval/results/e21_robustness.json | 2 +- tests/test_agent_hooks.py | 22 +++++++++- tests/test_harness_hooks_v2.py | 15 +++++-- tests/test_signer_policy.py | 35 ++++++++++++++++ tracekit/agent_hooks.py | 53 +++++++++++++++---------- tracekit/policy2/packs/coding.yaml | 12 +++--- 10 files changed, 111 insertions(+), 38 deletions(-) diff --git a/docs/coding-agents.md b/docs/coding-agents.md index de9ac8c27..3a1b66022 100644 --- a/docs/coding-agents.md +++ b/docs/coding-agents.md @@ -154,7 +154,7 @@ payloads and Tracekit's installer; not tested in a live Devin session. | Run id | `session_id` | `conversation_id` | `session_id` | `sessionID` | `session_id` | `session_id` | `session_id` | `session_id` | one task (each prompt, from `TaskStart` to `TaskComplete`), keyed on `sessionContext.rootSessionId` (the CLI's session, which `cline --id` resumes; its subagents' calls are in it too), else `taskId` | | Blocking a call | exit 2 + a reason on stderr (and `permissionDecision: deny`); on Windows exit 0 + the JSON deny, since PowerShell turns 2 into 1 and Codex reads the JSON only at 0 | exit 2 + `{"permission": "deny"}` | exit 2 + `{"decision": "deny"}` | the plugin throws before the tool runs when Tracekit blocks the call (exit 2) or the hook can't decide it (any other exit, or Python can't start) | exit 2 + a reason on stderr, stdout empty (a stray stdout line reads as no decision to goose) | exit 2 + a reason on stderr (Qwen Code ignores stdout at exit 2 and sends stderr to the model); nothing on stdout; on Windows the command ends in `; exit $LASTEXITCODE`, since PowerShell turns 2 into 1 | exit 2 + a reason on stderr and `hookSpecificOutput.permissionDecision: "deny"` | exit 2 + a reason on stderr | `{"cancel": true, "errorMessage": ...}` at exit 0 (Cline reads no exit status); a cancel stops the whole task, not only the call | | Tool call ids | from the harness | from the harness | none: paired by tool and arguments, first in first out | `callID` | `tool_call_id`, from the harness | `tool_use_id`, from the harness | none in documented stdin: paired by tool and arguments, first in first out | none in the documented payload: paired by tool and arguments, first in first out | the CLI's `tool_call.id`; the VS Code extension sends none: paired by tool and arguments, first in first out | -| Tool names | `Bash`; `write_stdin` → `Bash` (`command` = the typed `chars`; current Codex sends no hook for it, so what is typed into a running command isn't decided: [limits](limits.md#signer-and-capture)); `apply_patch` → `Edit` (`paths`: every file the patch adds, updates, deletes or moves to, its file headers read as Codex reads them, indented ones too); `apply_patch` run from the shell stays a `Bash` call, which the v2 coding pack holds for a person (`TK-A034`); MCP as `mcp__server__tool` | `Shell` → `Bash`; `Read`, `Write`, `Grep`; `Delete` → `Edit`, so the file rules read it; Cursor's hook sends an edit by any of its tools as a `Read` and then a `Write` of the whole file ([limits](limits.md#signer-and-capture)); the names its transcripts give its edit tools (3.29: `StrReplace`, `ApplyPatch`, `EditNotebook`; an older prompt's `search_replace`, `write`, `delete_file`, `edit_notebook`) → `Edit`, `Edit` (`paths`: every file a patch header names, in any argument), `NotebookEdit` (path: `target_notebook`), `Edit`, `Write`, `Edit`, `NotebookEdit`; every path the input names is decided (`file_path`, `path`, `target_file`, `filePath`, `target_notebook`: Cursor doesn't document which its tools read); `MCP:x` → `mcp__cursor__x`; other names pass through, which the policy treats as unknown tools | `run_shell_command` → `Bash`; `read_file` and `read_many_files` → `Read`; `write_file` → `Write`; `replace` → `Edit`; `grep_search` (`search_file_content` in older releases) → `Grep`; `glob`, `list_directory`, `web_fetch`, `google_web_search`; MCP tools, which Gemini CLI names `mcp__`, → `mcp___`; every path a file tool reads is decided, under each release's name for it (`file_path`, `absolute_path`, `dir_path`, `path`, and `read_many_files`' `paths` and `include`); `web_fetch` is decided on every URL its prompt names (`urls`) and on a `url` beside it | `bash` → `Bash`; `read`, `write`, `edit` (path: `filePath`); `apply_patch` (and 1.0's `patch`) → `Edit` (`paths`: every file its headers name, and a path with a `:` also up to it, as OpenCode 1.2 reads it); `batch` (experimental; OpenCode 1.x before 1.4 only: later releases and OpenCode 2 have none) is blocked: OpenCode runs the calls in it without plugin hooks; `glob`, `grep` (path: `path`); `webfetch`, `websearch`, `task`; MCP tools under OpenCode's `_` names, which the policy treats as unknown tools | `shell` → `Bash`; `write` → `Write` (path: `path`); `edit` → `Edit` (path: `path`); `tree` → `LS` (path: `path`); `read_image` → `Read` (path: `source`, not `path`); `__` → `mcp____`; other names pass through unchanged, which the policy treats as unknown tools | `run_shell_command` and `monitor` → `Bash`; `read_file` → `Read` (path: `file_path`, `absolute_path` before 0.13); `write_file` → `Write`; `edit` (and Gemini's `replace`) → `Edit`; `notebook_edit` → `NotebookEdit` (path: `notebook_path`); `grep_search` → `Grep`; `glob`, `list_directory`, `web_fetch`, `web_search`, `todo_write`; `agent` → `Task`; any other tool, MCP tools included, under its own name; file paths as for Gemini CLI; `web_fetch` is decided on its `url` and also on every URL its prompt names (Qwen Code fetches only the `url`) | `Execute` → `Bash`; `Create` → `Write`; `ApplyPatch` → `Edit` (`input`: complete patch; `paths`: all file headers); `FetchUrl` → `WebFetch`; other names, including `mcp__server__tool`, pass through | `exec` → `Bash` (`command` in any case, `\r` read as a line end; denied in the hook with no command, input that isn't an object, or a control character but a tab or line end); `write_to_process` → `Bash` (`command` = its one argument besides `shell_id`, the text it writes, whatever its name: its fields aren't documented; `\r` read as a line end; denied in the hook with any other argument, no text, a control character or a bash history expansion (`!-1`, a `^` starting a line) in the text, or text that sets shell state a later line runs: `fc`, an `alias` definition, a function, `trap`, the `exec` builtin, `PROMPT_COMMAND`, `LD_PRELOAD` …); a name sent twice to any tool, in any case, is denied in the hook; `read` → `Read`; `write` → `Write`; `edit` → `Edit` (each decided on every path under a key ending in `path`, `paths` or `file`, case and `_` ignored, and denied in the hook with none); `apply_patch` → `Edit` (`paths`: all patch file headers and a unified diff's file names; denied in the hook with none); `grep`, `glob`; `webfetch` → `WebFetch` (denied in the hook without a `url`, or with one under another spelling too); `mcp__server__tool` and other names pass through | `run_commands` → `Bash` (`command` for one command, `commands` for several, each decided on its own as Cline runs it in its own shell, a here-doc joined to its delimiter's line; from any shape Cline takes: a list, one command, `{command, args}`, `cmd`); `read_files` → `Read` (`paths`: every file, under `files`, `paths` or `file_paths`); `editor` → `Write` when it sends neither `old_text` nor `insert_line` (it then creates a missing file), else `Edit` (its `path`); `apply_patch` → `Edit` (`paths`: every file the patch names); `fetch_web_content` → `WebFetch` (`urls`: every request's URL); an MCP tool `__` → `mcp____`; a call none of these can be read from is cancelled; the other tools pass under their own names | +| Tool names | `Bash`; `write_stdin` → `Bash` (`command` = the typed `chars`; current Codex sends no hook for it, so what is typed into a running command isn't decided: [limits](limits.md#signer-and-capture)); `apply_patch` → `Edit` (`paths`: every file the patch adds, updates, deletes or moves to, its file headers read as Codex reads them, indented ones too); `apply_patch` run from the shell stays a `Bash` call, which the v2 coding pack holds for a person (`TK-A034`); MCP as `mcp__server__tool` | `Shell` → `Bash`; `Read`, `Write`, `Grep`; `Delete` → `Edit`, so the file rules read it; Cursor's hook sends an edit by any of its tools as a `Read` and then a `Write` of the whole file ([limits](limits.md#signer-and-capture)); the names its transcripts give its edit tools (3.29: `StrReplace`, `ApplyPatch`, `EditNotebook`; an older prompt's `search_replace`, `write`, `delete_file`, `edit_notebook`) → `Edit`, `Edit` (`paths`: every file a patch header names, in any argument), `NotebookEdit` (path: `target_notebook`), `Edit`, `Write`, `Edit`, `NotebookEdit`, each only with the file its tool reads (a patch with no file header, or a tool without its path, passes under its own name); every path the input names is decided (`file_path`, `path`, `target_file`, `filePath`, `target_notebook`: Cursor doesn't document which its tools read); `MCP:x` → `mcp__cursor__x`; other names pass through, which the policy treats as unknown tools | `run_shell_command` → `Bash`; `read_file` and `read_many_files` → `Read`; `write_file` → `Write`; `replace` → `Edit`; `grep_search` (`search_file_content` in older releases) → `Grep`; `glob`, `list_directory`, `web_fetch`, `google_web_search`; MCP tools, which Gemini CLI names `mcp__`, → `mcp___`; every path a file tool reads is decided, under each release's name for it (`file_path`, `absolute_path`, `dir_path`, `path`, and `read_many_files`' `paths` and `include`); `web_fetch` is decided on every URL its prompt names (`urls`) and on a `url` beside it | `bash` → `Bash`; `read`, `write`, `edit` (path: `filePath`); `apply_patch` (and 1.0's `patch`) → `Edit` (`paths`: every file its headers name, and a path with a `:` also up to it, as OpenCode 1.2 reads it); `batch` (experimental; OpenCode 1.x before 1.4 only: later releases and OpenCode 2 have none) is blocked: OpenCode runs the calls in it without plugin hooks; `glob`, `grep` (path: `path`); `webfetch`, `websearch`, `task`; MCP tools under OpenCode's `_` names, which the policy treats as unknown tools | `shell` → `Bash`; `write` → `Write` (path: `path`); `edit` → `Edit` (path: `path`); `tree` → `LS` (path: `path`); `read_image` → `Read` (path: `source`, not `path`); `__` → `mcp____`; other names pass through unchanged, which the policy treats as unknown tools | `run_shell_command` and `monitor` → `Bash`; `read_file` → `Read` (path: `file_path`, `absolute_path` before 0.13); `write_file` → `Write`; `edit` (and Gemini's `replace`) → `Edit`; `notebook_edit` → `NotebookEdit` (path: `notebook_path`); `grep_search` → `Grep`; `glob`, `list_directory`, `web_fetch`, `web_search`, `todo_write`; `agent` → `Task`; any other tool, MCP tools included, under its own name; file paths as for Gemini CLI; `web_fetch` is decided on its `url` and also on every URL its prompt names (Qwen Code fetches only the `url`) | `Execute` → `Bash`; `Create` → `Write`; `ApplyPatch` → `Edit` (`input`: complete patch; `paths`: all file headers); `FetchUrl` → `WebFetch`; other names, including `mcp__server__tool`, pass through | `exec` → `Bash` (`command` in any case, `\r` read as a line end; denied in the hook with no command, input that isn't an object, or a control character but a tab or line end); `write_to_process` → `Bash` (`command` = its one argument besides `shell_id`, the text it writes, whatever its name: its fields aren't documented; `\r` read as a line end; denied in the hook with any other argument, no text, a control character or a bash history expansion (`!-1`, a `^` starting a line) in the text, or text that sets shell state a later line runs: `fc`, an `alias` definition, a function, `trap`, the `exec` builtin, `PROMPT_COMMAND`, `LD_PRELOAD` …); a name sent twice to any tool, in any case, is denied in the hook; `read` → `Read`; `write` → `Write`; `edit` → `Edit` (each decided on every path under a key ending in `path`, `paths` or `file`, case and `_` ignored, and denied in the hook with none); `apply_patch` → `Edit` (`paths`: all patch file headers and a unified diff's file names; denied in the hook with none); `grep`, `glob`; `webfetch` → `WebFetch` (denied in the hook without a `url`, or with one under another spelling too); `mcp__server__tool` and other names pass through | `run_commands` → `Bash` (`command` for one command, `commands` for several, each decided on its own as Cline runs it in its own shell, a here-doc joined to its delimiter's line; from any shape Cline takes: a list, one command, `{command, args}`, `cmd`); `read_files` → `Read` (`paths`: every file, under `files`, `paths` or `file_paths`); `editor` → `Write` when it sends neither `old_text` nor `insert_line` (it then creates a missing file), else `Edit` (its `path`); `apply_patch` → `Edit` (`paths`: every file the patch names); `fetch_web_content` → `WebFetch` (`urls`: every request's URL); an MCP tool `__` → `mcp____`; a call none of these can be read from is cancelled; the other tools pass under their own names | What is the same as Claude Code: the policy gate runs before the tool (deny blocks; ask blocks the call until someone approves it from another terminal, then the agent's retry runs: [held calls](#held-calls-approve-then-retry)), events diff --git a/docs/limits.md b/docs/limits.md index 023ba5683..95c5d4519 100644 --- a/docs/limits.md +++ b/docs/limits.md @@ -181,7 +181,7 @@ What Tracekit guarantees and doesn't, per deployment, on one page: [guarantees]( | On the dev signer, an app's own tool named `Agent`, `Task`, `SendMessage`, `SubagentHandback` or `TodoWrite` (an SDK agent's, not Claude Code's) is read as a coding agent's message to its own agents (class `harness`): the file names in its arguments aren't read by `TK-S004` or `TK-F005`, a `SendMessage` is flagged as one, and an `Agent` or `Task` whose arguments hold `"isolation":"remote"` is held. | The policy maps tools by name; the dev signer serves coding agents' hooks and SDK apps alike. | Name your app's tools otherwise, or map them in a policy of your own (`tools:`), which wins over the pack's. | [policy](policy-v2.md#packs-shipped) | | `TK-A056` reads a remote's push or mirror setting only when the push line gives it (`git -c remote.origin.push=HEAD:main push origin feature` is held). One set earlier with `git config remote.origin.push …` (`TK-A013` doesn't hold that), in the repository's config or in a global one, sends a later `git push origin feature` where it says, to main too, and the push stays flagged. | The push line is all a rule reads; the config file isn't read when a call is decided. | Protect the default branch on the remote; review a change to `remote.*.push` in a repository's config. | [policy](policy-v2.md#packs-shipped) | | A single message, email or post sent outside isn't held: `gh issue create`, `gh pr comment`, one email or a chat MCP tool's message is recorded (an MCP call flagged, `TK-F006`); a secret in it is denied (`TK-S002`), and so are mass email and a whole-channel notice (`TK-M003`, `TK-M004`, held). | No rule reads what a single message says. | Add an `ask` rule of your own for the messaging tools your agents have. | [policy](policy-v2.md#packs-shipped) | -| An agent's edit of its own harness's settings, hooks, MCP servers, skills or slash commands (`.claude/settings.json`, `~/.claude.json`, `.claude/skills/` and `.claude/commands/`, whose `!` lines run commands, `~/.gemini/settings.json`, `.codex/`, `~/.cursor/hooks.json` and `mcp.json`, OpenCode's `.opencode/`, `opencode.json` and, from the shell, `~/.config/opencode` or `$XDG_CONFIG_HOME/opencode` (the shell rule matches the variable's name; a file tool gets the expanded path, so its write is denied only at `~/.config/opencode`, `TK-D009`), Qwen Code's `.qwen/` and `~/.qwen/settings.json`, Factory Droid's `.factory/`, Devin's `.devin/`, `~/.config/devin` and, on Windows, `AppData\Roaming\devin` (the folder `%APPDATA%` names: a path written through the variable isn't matched), Antigravity CLI's `~/.gemini/config/hooks.json` and `.agents/hooks.json`, goose's `.agents/plugins/` and `~/.config/goose`, Crush's `crush.json`, `.crush.json`, `crushrc`, `.crushrc` and `~/.config/crush`, PowerShell's profiles (a `*profile.ps1` in `Documents/WindowsPowerShell/` or `Documents/PowerShell/`, OneDrive's Documents too under its localized name (`OneDrive - Contoso/Dokumente/`), pwsh's `~/.config/powershell/` on Linux and macOS, or the `$PSHOME` of Windows PowerShell (`System32/WindowsPowerShell/v1.0/`) or PowerShell 7 (`PowerShell/7/`, `PowerShell/7-preview/`), and `$PROFILE` or `$global:PROFILE` by name from the shell), which run before a hook PowerShell starts without `-NoProfile`, by a file-editing tool (Write, Edit, MultiEdit or NotebookEdit) or a recognized shell write) is held (`TK-F009`, `TK-F015`, since #604); one the rules don't read (below) runs, and once it turns the sandbox off, `TK-A003`, `TK-A004` and `TK-A014` have nothing to hold: later commands run outside it with no escape-hatch argument. The file rule reads the normalized path, and the shell rule reads `WRITE_TARGET:` and `DELETE_TARGET:` effects (redirects, `tee`, `cp`, `mv`, `sed -i`, `rm`, `find -delete`, `git rm`, awk's `print > "file"`, …). Both also match casefolded paths. Reads and content that merely names these paths do not match. Not flagged: Cursor's rules (`.cursor/rules/`), Windsurf's and VS Code's settings, a Claude Code config folder moved elsewhere (`CLAUDE_CONFIG_DIR`, `~/.config/claude-code`) and instruction files agents edit in ordinary work (`AGENTS.md`, `CLAUDE.md`); `TK-F016`/`TK-F017` read an `ANTHROPIC_…BASE_URL` name only when it is written in one piece (not split by a line continuation), and not a proxy variable (`HTTPS_PROXY`). A file inside one of Claude Code's worktrees (`.claude/worktrees//…`) is read as it is in the worktree: an ordinary file there isn't flagged, the worktree's own `.claude/`, `.codex/`, `.mcp.json` and the rest are, and so is a worktree named as a dot folder, the worktree itself, and a shell target with a `..`, or an expansion or glob that can make one (`$D`, `{..,a}`, `.*`), among its first 32 parts after the worktree, or more parts than that. A link made in a worktree that points out of it (`ln -s ../.. .claude/worktrees/x/up`, then a write to `up/settings.json`) isn't followed, as a link made anywhere else isn't. `ANTHROPIC_BASE_URL` (where the agent's model calls go) is flagged wherever a call names it, in any case (Windows reads a variable's name so): in a Write, Edit or MultiEdit call's arguments (`TK-F016`; a NotebookEdit cell isn't read) and on a shell line from any shell tool, an assignment prefix (`ANTHROPIC_BASE_URL=x claude`) and the text a heredoc or `echo` writes included (`TK-F017`). A mention is flagged as well as a setting, so a grep, a note or a comment that names the variable is flagged too: noisy by design, and only a flag. Under `QWEN_HOME`, the shell rule matches only the variable's name (`$QWEN_HOME/settings.json`); a file tool's write to the directory it names is not matched. A write through any other variable, a script or another program (`curl -o`, `wget -O`, `touch`, `rsync`, `git restore`, an editor, an interpreter one-liner) is not matched, nor is a PowerShell cmdlet that writes or deletes a profile (`Add-Content`, `Set-Content`, `Out-File`, `Remove-Item`) or a profile in a Documents folder redirected elsewhere (a path without `Documents` or `OneDrive`). | The rules cover every file under those directories (skills, commands) but Claude Code's memory notes (`.claude/projects//memory/*.md`, the agent's own notes, not settings) and the ordinary files of its worktrees (a checkout of the project, not settings); agents edit those files in normal work. The rest are held: on one developer's week of Tracekit work, 19 calls in 7 days, 13 of them test fixtures written in scratch folders or a worktree's removal. | Approve a held settings change only when you meant it; keep the sandbox's settings where the agent can't write (managed settings, a read-only mount); add an `ask` rule of your own for the settings files your agents never need to touch. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#what-tracekit-sees-and-doesnt), [Gemini CLI's sandbox](integrations/gemini-sandbox.md) | +| An agent's edit of its own harness's settings, hooks, MCP servers, skills or slash commands (`.claude/settings.json`, `~/.claude.json`, `.claude/skills/` and `.claude/commands/`, whose `!` lines run commands, `~/.gemini/settings.json`, `.codex/`, `~/.cursor/hooks.json` and `mcp.json`, OpenCode's `.opencode/`, `opencode.json` and, from the shell, `~/.config/opencode` or `$XDG_CONFIG_HOME/opencode` (the shell rule matches the variable's name; a file tool gets the expanded path, so its write is denied only at `~/.config/opencode`, `TK-D009`), Qwen Code's `.qwen/` and `~/.qwen/settings.json`, Factory Droid's `.factory/`, Devin's `.devin/`, `~/.config/devin` and, on Windows, `AppData\Roaming\devin` (the folder `%APPDATA%` names: a path written through the variable isn't matched), Antigravity CLI's `~/.gemini/config/hooks.json` and `.agents/hooks.json`, goose's `.agents/plugins/` and `~/.config/goose`, Crush's `crush.json`, `.crush.json`, `crushrc`, `.crushrc` and `~/.config/crush`, PowerShell's profiles (a `*profile.ps1` in `Documents/WindowsPowerShell/` or `Documents/PowerShell/`, OneDrive's Documents too under its localized name (`OneDrive - Contoso/Dokumente/`), pwsh's `~/.config/powershell/` on Linux and macOS, or the `$PSHOME` of Windows PowerShell (`System32/WindowsPowerShell/v1.0/`) or PowerShell 7 (`PowerShell/7/`, `PowerShell/7-preview/`), and `$PROFILE` or `$global:PROFILE` by name from the shell), which run before a hook PowerShell starts without `-NoProfile`, by a file-editing tool (Write, Edit, MultiEdit or NotebookEdit) or a recognized shell write) is held (`TK-F009`, `TK-F015`, since #604); one the rules don't read (below) runs, and once it turns the sandbox off, `TK-A003`, `TK-A004` and `TK-A014` have nothing to hold: later commands run outside it with no escape-hatch argument. The file rule reads the normalized path, and the shell rule reads `WRITE_TARGET:` and `DELETE_TARGET:` effects (redirects, `tee`, `cp`, `mv`, `sed -i`, `rm`, `find -delete`, `git rm`, awk's `print > "file"`, …). Both also match casefolded paths. Reads and content that merely names these paths do not match. Not flagged: Cursor's rules (`.cursor/rules/`), Windsurf's and VS Code's settings, a Claude Code config folder moved elsewhere (`CLAUDE_CONFIG_DIR`, `~/.config/claude-code`) and instruction files agents edit in ordinary work (`AGENTS.md`, `CLAUDE.md`); `TK-F016`/`TK-F017` read an `ANTHROPIC_…BASE_URL` name only when it is written in one piece (not split by a line continuation), and not a proxy variable (`HTTPS_PROXY`). A file inside one of Claude Code's worktrees (`.claude/worktrees//…`) is read as it is in the worktree: an ordinary file there isn't flagged, the worktree's own `.claude/`, `.codex/`, `.mcp.json` and the rest are, and so is a worktree named as a dot folder, the worktree itself, and a shell target with a `..`, or an expansion or glob that can make one (`$D`, `{..,a}`, `.*`), among its first 32 parts after the worktree, or more parts than that. A link made in a worktree that points out of it (`ln -s ../.. .claude/worktrees/x/up`, then a write to `up/settings.json`) isn't followed, as a link made anywhere else isn't. `ANTHROPIC_BASE_URL` (where the agent's model calls go) is flagged wherever a call names it, in any case (Windows reads a variable's name so): in a Write, Edit, MultiEdit or NotebookEdit call's arguments (`TK-F016`) and on a shell line from any shell tool, an assignment prefix (`ANTHROPIC_BASE_URL=x claude`) and the text a heredoc or `echo` writes included (`TK-F017`). A mention is flagged as well as a setting, so a grep, a note or a comment that names the variable is flagged too: noisy by design, and only a flag. Under `QWEN_HOME`, the shell rule matches only the variable's name (`$QWEN_HOME/settings.json`); a file tool's write to the directory it names is not matched. A write through any other variable, a script or another program (`curl -o`, `wget -O`, `touch`, `rsync`, `git restore`, an editor, an interpreter one-liner) is not matched, nor is a PowerShell cmdlet that writes or deletes a profile (`Add-Content`, `Set-Content`, `Out-File`, `Remove-Item`) or a profile in a Documents folder redirected elsewhere (a path without `Documents` or `OneDrive`). | The rules cover every file under those directories (skills, commands) but Claude Code's memory notes (`.claude/projects//memory/*.md`, the agent's own notes, not settings) and the ordinary files of its worktrees (a checkout of the project, not settings); agents edit those files in normal work. The rest are held: on one developer's week of Tracekit work, 19 calls in 7 days, 13 of them test fixtures written in scratch folders or a worktree's removal. | Approve a held settings change only when you meant it; keep the sandbox's settings where the agent can't write (managed settings, a read-only mount); add an `ask` rule of your own for the settings files your agents never need to touch. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#what-tracekit-sees-and-doesnt), [Gemini CLI's sandbox](integrations/gemini-sandbox.md) | | `TK-A003` holds a call only when it carries `dangerouslyDisableSandbox: true`. Commands matching `excludedCommands`, hooks and MCP servers run outside the sandbox without it. | Claude Code marks only the unsandboxed retry; the rest are outside the sandbox by configuration. | Keep `excludedCommands` short; the policy still decides each excluded command and MCP tool call. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#what-tracekit-sees-and-doesnt) | | `TK-A014` holds a call whose `allowed_domains` names a host; it doesn't see hosts opened by the sandbox's own settings (`network.allowedDomains`), and it can't tell which of the listed hosts a command then reached. **(1.5.1)** It reads only Bash, PowerShell and Monitor calls, the tools Claude Code documents as opening hosts this way (WebSearch's `allowed_domains` only narrows results): a new tool that opens hosts with `allowed_domains` isn't held until the pack names it. | The hook sees the call's arguments, not the sandbox's settings or its proxy's traffic. | Keep the hosts a project always needs in `network.allowedDomains` (a person edits the settings) and approve the rest one command at a time. | [Claude Code's sandbox](integrations/claude-code-sandbox.md#per-command-allowed-domains-tk-a014) | | A tool name a framework rewrote (CrewAI's `bash` for `Bash`, `multi_edit` for `MultiEdit`) is also decided as the tool `tools:` lists with that spelling (case, accents, spaces and punctuation ignored), as each one when two listed names share it (the server pack's `bash` and `Bash`), and its results are untrusted when that tool's are; an MCP tool's bare name is read the same way. Nothing else reads it so: a rule whose `tool:` names a tool `tools:` doesn't list (`tool: RefundTool`, which CrewAI sends as `refund_tool`) doesn't take it, and constraints, the egress observer's host, detection's sum limits and a fail mode in an outage go by the class of the name as sent (`unknown`); an agent approver can't answer it, as the policy doesn't name it exactly. A name with no ASCII letter or digit, or a name over 64 characters (CrewAI cuts it and adds a hash) is decided only as sent. Each name a call is decided as gets the fallback regex engine's time budget of its own, so on a crafted 64 KiB argument a renamed tool's decision can take a second per name (re2 is unaffected). | A `tool:` pattern can't be spelled backwards; deciding both names and keeping the stricter decision never decides a call less strictly than before. | List each tool under its declared name in `tools:` (`RefundTool: app`), or write a rule's `tool:` as the framework sends it; keep the `default` fail mode closed, as it ships. | [policy](policy-v2.md#classes-and-fields), [CrewAI](integrations/crewai.md) | diff --git a/eval/results/e17_policy_corpus.json b/eval/results/e17_policy_corpus.json index 7afb65c7c..c7176f37c 100644 --- a/eval/results/e17_policy_corpus.json +++ b/eval/results/e17_policy_corpus.json @@ -1,5 +1,5 @@ { - "policy_hash": "sha256:61e6357013eed239e70619feb253543b654931c8a003ed756b92e48e17276a43", + "policy_hash": "sha256:40354f329b6c4b0b9a3365a26f5a1c5e39edb2ae7e49e46d65d7702afc4dfc71", "engines": [ "re2@1.1.20251105", "regex@2026.9.29" diff --git a/eval/results/e21_policy_robustness.json b/eval/results/e21_policy_robustness.json index 384e50d21..8097dd193 100644 --- a/eval/results/e21_policy_robustness.json +++ b/eval/results/e21_policy_robustness.json @@ -10,7 +10,7 @@ "profiles": { "default": { "pack": "server.yaml", - "policy_hash": "sha256:61e6357013eed239e70619feb253543b654931c8a003ed756b92e48e17276a43", + "policy_hash": "sha256:40354f329b6c4b0b9a3365a26f5a1c5e39edb2ae7e49e46d65d7702afc4dfc71", "heldout": { "recall": 0.6071428571428571, "deny_recall": 0.2761904761904762, @@ -2708,7 +2708,7 @@ }, "strict": { "pack": "strict.yaml", - "policy_hash": "sha256:00a117e591024d5e2ca2466530959850034c99cb9d5799ae340e4aabf54133d8", + "policy_hash": "sha256:c8a44ce16312d694df4308b59e17d007f9ffc993577b6f64a74fefd657c777f5", "heldout": { "recall": 0.6785714285714286, "deny_recall": 0.36666666666666664, diff --git a/eval/results/e21_robustness.json b/eval/results/e21_robustness.json index ca410efdd..a7aab7b44 100644 --- a/eval/results/e21_robustness.json +++ b/eval/results/e21_robustness.json @@ -4475,7 +4475,7 @@ } } }, - "policy_hash": "sha256:61e6357013eed239e70619feb253543b654931c8a003ed756b92e48e17276a43", + "policy_hash": "sha256:40354f329b6c4b0b9a3365a26f5a1c5e39edb2ae7e49e46d65d7702afc4dfc71", "regressions": [], "rewrite_missed": [], "rewritten_cases": 511, diff --git a/tests/test_agent_hooks.py b/tests/test_agent_hooks.py index 31d2c28af..2c8435002 100644 --- a/tests/test_agent_hooks.py +++ b/tests/test_agent_hooks.py @@ -1072,7 +1072,8 @@ def test_each_is_decided_on_the_file_its_tool_reads(self): "NotebookEdit"), (("edit_notebook", {"target_notebook": env}), "NotebookEdit"), (("ApplyPatch", {"patch": patch, "path": decoy, "file_path": decoy}), "Edit"), - (("ApplyPatch", patch), "Edit")): + (("ApplyPatch", patch), "Edit"), + (("ApplyPatch", {"patch": patch.replace("\n", "\r")}), "Edit")): # the review of #767 with self.subTest(form=form): mapped, ti = agent_hooks.tool("cursor", *form) self.assertEqual(mapped, tool) @@ -1083,6 +1084,25 @@ def test_each_is_decided_on_the_file_its_tool_reads(self): _, ti = agent_hooks.tool("cursor", "ApplyPatch", {"patch": patch}) self.assertEqual((ti["file_path"], ti["paths"]), (decoy, [decoy, env])) + def test_one_naming_no_file_is_left_to_the_v1_policy_as_before(self): + # the review of #767: an edit Tracekit can't read a file from was mapped to an Edit of no file + from tracekit import policy + v1 = policy.load(policy.DEFAULT_POLICY)[0] + for name, ti in (("ApplyPatch", {"patch": "*** Begin Patch\n@@\n-a\n+b\n*** End Patch\n"}), ("ApplyPatch", {}), + ("StrReplace", {"old_string": "a", "new_string": "b"}), ("EditNotebook", {"cell_idx": 0})): + with self.subTest(name=name, input=ti): + mapped, args = agent_hooks.tool("cursor", name, ti) + self.assertEqual(mapped, name) + self.assertEqual(policy.evaluate(v1, mapped, args, "/w")["decision"], "allow") # main's v1 decision + + def test_a_long_run_of_spaces_takes_linear_time(self): + # the review of #767: trimming with a regex took 4.65 s on a line of 40,000 spaces (OpenCode's too) + line = " " * 40_000 + "x" + start = time.process_time() + agent_hooks.tool("cursor", "ApplyPatch", {"patch": f"*** Begin Patch\n*** Update File: a.py\n{line}\n*** End Patch"}) + agent_hooks.tool("opencode", "apply_patch", {"patchText": f"*** Begin Patch\n*** Update File: a.py{line}\n"}) + self.assertLess(time.process_time() - start, 1.0) + class CodexPatchHeaders(unittest.TestCase): """Codex (codex-rs/apply-patch) reads a hunk header after Begin Patch, an Add or a Delete hunk from the line with its diff --git a/tests/test_harness_hooks_v2.py b/tests/test_harness_hooks_v2.py index d35ea6303..9ab5e51f9 100644 --- a/tests/test_harness_hooks_v2.py +++ b/tests/test_harness_hooks_v2.py @@ -578,7 +578,10 @@ def call(i, name, ti, ev="preToolUse"): ("write", {"file_path": hooks, "contents": "{}"}), ("ApplyPatch", {"patch": patch}), ("ApplyPatch", patch), ("EditNotebook", {"target_notebook": hooks, **cell}), - ("edit_notebook", {"target_notebook": hooks, **cell}))): + ("edit_notebook", {"target_notebook": hooks, **cell}), + # Cursor reads \r as a line end (the review of #767: this patch was allowed) + ("ApplyPatch", {"patch": patch.replace("\n", "\r")}), + ("ApplyPatch", json.dumps({"patch": patch.replace("\n", "\r")})))): with self.subTest(tool=name, input=ti): code, out, err = call(i, name, ti) self.assertEqual((code, json.loads(out)["permission"]), (2, "deny"), err) @@ -591,14 +594,20 @@ def call(i, name, ti, ev="preToolUse"): code, out, err = call(i, name, {key: "/w/.env"}) self.assertEqual((code, json.loads(out)["permission"]), (2, "deny"), name) self.assertIn("TK-D005", err) + # an edit naming no file Tracekit can read stays an unknown tool, as before + for i, (name, ti) in enumerate((("ApplyPatch", {"patch": "*** Begin Patch\n@@\n-a\n+b\n*** End Patch\n"}), + ("StrReplace", {"old_string": "a", "new_string": "b"})), 30): + self.assertEqual(call(i, name, ti)[0], 0, name) st, c = claude_code._load(claude_code._state(sid)), Client() self.addCleanup(c.close) evs = c.call("read", {"run_id": st["run_id"], "run_token": st["run_token"], "limit": 100})["events"] decided = {e["data"]["tool_use_id"]: (e["data"]["tool"], e["data"]["rule_ids"]) for e in evs if e["type"] == "policy.decision"} self.assertEqual(decided["e20"], ("Edit", [])) - self.assertEqual([decided[f"e{i}"][0] for i in range(1, 8)], - ["Edit", "Edit", "Write", "Edit", "Edit", "NotebookEdit", "NotebookEdit"]) + self.assertEqual([decided[f"e{i}"][0] for i in range(1, 10)], + ["Edit", "Edit", "Write", "Edit", "Edit", "NotebookEdit", "NotebookEdit", "Edit", "Edit"]) + self.assertEqual((decided["e30"], decided["e31"]), + (("ApplyPatch", ["TK-UNKNOWN-TOOL"]), ("StrReplace", ["TK-UNKNOWN-TOOL"]))) def test_a_devin_file_call_is_decided_on_every_path_its_input_names(self): # the review of #576: the signer decided only the first path key, so a decoy file_path beside the path Devin's diff --git a/tests/test_signer_policy.py b/tests/test_signer_policy.py index 0337e709a..aba31a0e6 100644 --- a/tests/test_signer_policy.py +++ b/tests/test_signer_policy.py @@ -2302,6 +2302,9 @@ def test_cursor_edit_tools_are_decided_as_the_edits_they_are(self): (("ApplyPatch", {"patch": json.dumps({"patch": patch})}), ("Edit", {"file_path": path})), (("ApplyPatch", {"patch": patch.replace("*** Update", " *** Update"), "path": "/w/a.txt"}), ("Edit", {"file_path": path})), + # and reads \r and \r\n as line ends (the review of #767: a CR-only patch was decided on no file) + (("ApplyPatch", {"patch": patch.replace("\n", "\r")}), ("Edit", {"file_path": path})), + (("ApplyPatch", patch.replace("\n", "\r\n")), ("Edit", {"file_path": path})), (("EditNotebook", {"target_notebook": path, **cell}), ("NotebookEdit", {"notebook_path": path})), (("edit_notebook", {"target_notebook": path, **cell}), ("NotebookEdit", {"notebook_path": path}))) for pack, engine, e in self.every_pack(): @@ -2317,6 +2320,38 @@ def test_cursor_edit_tools_are_decided_as_the_edits_they_are(self): else: self.assertNotIn("TK-UNKNOWN-TOOL", got["rule_ids"]) + def test_a_cursor_edit_naming_no_file_stays_an_unknown_tool(self): + # the review of #767: an edit Tracekit can't read a file from was decided as an Edit of no file, allowed, where + # before it was an unknown tool (flagged on dev and coding, held on server and strict) + from tracekit import agent_hooks + forms = (("ApplyPatch", {"patch": "*** Begin Patch\n@@\n-a\n+b\n*** End Patch\n"}), ("ApplyPatch", {}), + ("ApplyPatch", ""), ("ApplyPatch", {"patch": 5}), ("ApplyPatch", {"patch": "*** Update File: \n"}), + ("StrReplace", {"old_string": "a", "new_string": "b"}), + ("StrReplace", {"path": ["/w/.env"], "file_path": "/w/a.py", "old_string": "a", "new_string": "b"}), + ("search_replace", {"path": "/w/a.py", "old_string": "a", "new_string": "b"}), + ("write", {"contents": "x"}), ("delete_file", {"path": "/w/a.py"}), + ("EditNotebook", {"cell_idx": 0, "new_string": "x"}), + ("edit_notebook", {"target_notebook": ["/w/a.ipynb"], "file_path": "/w/a.ipynb"})) + for pack, engine, e in self.every_pack(): + for name, ti in forms: + with self.subTest(pack=pack, engine=engine, name=name, input=ti): + mapped, args = agent_hooks.tool("cursor", name, ti) + d = e.decide(mapped, args) + self.assertEqual(mapped, name) + self.assertIn("TK-UNKNOWN-TOOL", d["rule_ids"]) + self.assertNotEqual(d["verdict"], "allow") + + def test_a_notebook_edit_naming_the_model_endpoint_is_flagged(self): + # TK-F016 read Write, Edit and MultiEdit only (the review of #767): a notebook cell setting it was not flagged + from tracekit import agent_hooks + cell = "import os\nos.environ['ANTHROPIC_BASE_URL'] = 'http://127.0.0.1:9/'\n" + for pack, engine, e in self.every_pack(): + for tool, args in (("NotebookEdit", {"notebook_path": "/w/a.ipynb", "new_source": cell}), + agent_hooks.tool("cursor", "EditNotebook", {"target_notebook": "/w/a.ipynb", "cell_idx": 0, + "old_string": "", "new_string": cell})): + with self.subTest(pack=pack, engine=engine, tool=tool): + self.assertIn("TK-F016", e.decide(tool, args)["rule_ids"]) + def test_opencode_config_changes_are_flagged_but_reads_and_near_names_are_allowed(self): for tool, path in (("Write", "/repo/.opencode/commands/deploy.md"), ("Write", "/repo/.opencode/plugin/tracekit.ts"), diff --git a/tracekit/agent_hooks.py b/tracekit/agent_hooks.py index 64a76cdd7..90603163c 100644 --- a/tracekit/agent_hooks.py +++ b/tracekit/agent_hooks.py @@ -108,13 +108,19 @@ # a URL in Gemini CLI's web_fetch prompt: its scheme in any case (WHATWG URL parsing), up to a character JavaScript's # \s matches (the prompt is split on them) WEB_FETCH_URL = re.compile(r"https?://[^\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+", re.I) +# what JavaScript's trim() takes off a string's ends: str.strip(JS_SPACE) does the same, in linear time +JS_SPACE = "\t\n\v\f\r \u00a0\u1680" + "".join(map(chr, range(0x2000, 0x200b))) + "\u2028\u2029\u202f\u205f\u3000\ufeff" # Cursor's hooks name a call by what it does on the computer: an edit by any of its tools reaches preToolUse as a Read and -# then a Write of the whole file (file_path, content). Its transcripts name the model's tools (Cursor 3.29): StrReplace, -# Write, Delete, EditNotebook, ApplyPatch, and an older prompt's search_replace, write, delete_file and edit_notebook. +# then a Write of the whole file (file_path, content). # A Delete is an Edit, as a Codex patch's Delete File is: the file rules (a credentials file, the transcripts) read it -CURSOR_TOOLS = {"Shell": "Bash", "Read": "Read", "Write": "Write", "Grep": "Grep", "Delete": "Edit", "Task": "Task", - "Edit": "Edit", "StrReplace": "Edit", "search_replace": "Edit", "write": "Write", "delete_file": "Edit", - "EditNotebook": "NotebookEdit", "edit_notebook": "NotebookEdit"} +CURSOR_TOOLS = {"Shell": "Bash", "Read": "Read", "Write": "Write", "Grep": "Grep", "Delete": "Edit", "Task": "Task", "Edit": "Edit"} +# Its transcripts name the model's edit tools (Cursor 3.29.15): StrReplace, EditNotebook, and an older prompt's +# search_replace, write, delete_file and edit_notebook, each with the argument its file is in. Cursor refuses a call +# without a string there; Tracekit then leaves the name unmapped, an unknown tool, as it does an ApplyPatch with no +# file header, rather than decide an edit of no file +CURSOR_EDITS = {"StrReplace": ("Edit", "path"), "search_replace": ("Edit", "file_path"), "write": ("Write", "file_path"), + "delete_file": ("Edit", "target_file"), "EditNotebook": ("NotebookEdit", "target_notebook"), + "edit_notebook": ("NotebookEdit", "target_notebook")} CURSOR_PATH_ARGS = ("file_path", "path", "target_file", "filePath", "target_notebook") OPENCODE_TOOLS = {"bash": "Bash", "read": "Read", "write": "Write", "edit": "Edit", "apply_patch": "Edit", "patch": "Edit", "glob": "Glob", "grep": "Grep", "webfetch": "WebFetch", "websearch": "WebSearch", @@ -222,7 +228,6 @@ def _diff_names(name): KILO_BLOCKED = ("notebook_execute",) # the harnesses that load Tracekit's OpenCode plugin: their tool names and the argument each file tool reads PLUGIN_TOOLS = {"opencode": (OPENCODE_TOOLS, OPENCODE_PATH_ARG), "kilo": (KILO_TOOLS, KILO_PATH_ARG)} -JS_TRIM = re.compile(r"^[\s\ufeff]+|[\s\ufeff]+$") # Cline's tools that run a command, read or write a file or fetch a URL (sdk/packages/core/src/extensions/tools). Its # PreToolUse hook sees a call before Cline checks the input against the tool's schema, which takes several shapes # (schemas.ts: run_commands a list, one command, {command, args} run without a shell, or cmd; read_files files, paths @@ -261,7 +266,7 @@ def _cline_commands(v): m, end = CLINE_HEREDOC.search(lines[0]), 0 if m: end = next((i for i, x in enumerate(lines[1:], 1) - if JS_TRIM.sub("", x) == next(filter(None, m.groups()))), 0) + if x.strip(JS_SPACE) == next(filter(None, m.groups()))), 0) out.append("\n".join(lines[:end + 1])) lines = lines[end + 1:] if c is None: @@ -378,20 +383,24 @@ def tool(harness, name, ti): if name.startswith("MCP:"): return "mcp__cursor__" + re.sub(r"[^A-Za-z0-9_-]+", "_", name[4:]), ti if name == "ApplyPatch": # every file a patch header names, in whichever argument holds it, as Cursor reads it: - # a {"patch": ...} in JSON unwrapped, each line trimmed as JavaScript trims it + # a {"patch": ...} in JSON unwrapped, \r and \r\n read as \n, each line trimmed as JavaScript trims it texts = list(_strings(ti)) for s in texts[:]: - with contextlib.suppress(ValueError, RecursionError): - j = json.loads(JS_TRIM.sub("", s)) - if isinstance(j, dict) and list(j) == ["patch"] and isinstance(j["patch"], str): - texts.append(j["patch"]) - lines = "\n".join(JS_TRIM.sub("", x) for x in "\n".join(texts).split("\n")) - ti["paths"] = files = [JS_TRIM.sub("", f) for f in PATCH_FILE.findall(lines)] - ti["file_path"] = files[0] if files else None - return "Edit", ti - if name in ("EditNotebook", "edit_notebook"): # it reads target_notebook; v1 decides a NotebookEdit on its - # file_path and notebook_path - ti["file_path"] = ti["notebook_path"] = ti.get("target_notebook") + if s.strip(JS_SPACE).startswith("{"): + with contextlib.suppress(ValueError, RecursionError): + j = json.loads(s.strip(JS_SPACE)) + if isinstance(j, dict) and list(j) == ["patch"] and isinstance(j["patch"], str): + texts.append(j["patch"]) + lines = "\n".join(x.strip(JS_SPACE) for x in re.sub(r"\r\n?", "\n", "\n".join(texts)).split("\n")) + files = [f for f in (g.strip(JS_SPACE) for g in PATCH_FILE.findall(lines)) if f] + if files: + ti["paths"], ti["file_path"] = files, files[0] + return "Edit", ti + edit = CURSOR_EDITS.get(name) + if edit and not isinstance(ti.get(edit[1]), str): # no file to decide it on: left unmapped (CURSOR_EDITS) + edit = None + if edit and edit[0] == "NotebookEdit": # v1 decides a NotebookEdit on its file_path and notebook_path + ti["file_path"] = ti["notebook_path"] = ti["target_notebook"] for k in CURSOR_PATH_ARGS[1:]: if k in ti and "file_path" not in ti: ti["file_path"] = ti[k] @@ -401,7 +410,7 @@ def tool(harness, name, ti): files = [ti[k] for k in CURSOR_PATH_ARGS if isinstance(ti.get(k), str)] if any(f not in [ti["file_path"], *paths] for f in files): ti["paths"] = list(dict.fromkeys(files + paths)) - return CURSOR_TOOLS.get(name, name), ti + return edit[0] if edit else CURSOR_TOOLS.get(name, name), ti if harness == "gemini" and name.startswith("mcp_"): # mcp__ (packages/core/src/tools/mcp-tool.ts) return "mcp__" + name[4:], ti if harness in ("gemini", "qwen"): @@ -447,7 +456,7 @@ def tool(harness, name, ti): if name in ("apply_patch", "patch"): # every file OpenCode's parser finds, whatever paths the model sent (patch: # 1.0's tool, off by default, with the same parser and argument); releases of 2026-01-18 to 2026-02-23 # (1.2.0) read a header only up to its next ':' (split(":", 2)): both are decided - files = [JS_TRIM.sub("", g) for f in OPENCODE_PATCH_FILE.findall(str(ti.get("patchText") or "")) + files = [g.strip(JS_SPACE) for f in OPENCODE_PATCH_FILE.findall(str(ti.get("patchText") or "")) for g in dict.fromkeys((f, f.split(":")[0]))] ti["paths"] = files ti["file_path"] = files[0] if files else None @@ -516,7 +525,7 @@ def tool(harness, name, ti): if isinstance(new, str): ti["new_string"] = new elif name == "apply_patch": # the patch is its `input`, or the whole input as a string - files = [JS_TRIM.sub("", f) for f in PATCH_FILE.findall(str(v.get("input") if one else v))] # JS trim() + files = [f.strip(JS_SPACE) for f in PATCH_FILE.findall(str(v.get("input") if one else v))] # JS trim() if not files or not all(files): raise ValueError("Cline's apply_patch names no file") ti["file_path"], ti["paths"] = files[0], files diff --git a/tracekit/policy2/packs/coding.yaml b/tracekit/policy2/packs/coding.yaml index b29a97a6d..49180a9c6 100644 --- a/tracekit/policy2/packs/coding.yaml +++ b/tracekit/policy2/packs/coding.yaml @@ -11,7 +11,7 @@ # agent's file system may ignore case). Rules stay tripwires: the protection is the signer, its storage and the # witnesses. -version: '2026.11-v2-81' +version: '2026.11-v2-83' description: coding agents on a laptop (Claude Code, Codex, Cursor, Gemini) # laptop: a tool the pack does not map is flagged, not held; server.yaml holds it for a person (ask) unknown_tools: flag @@ -991,12 +991,12 @@ flag: label: background_spawn - id: TK-F016 class: fs - tool: Write|Edit|MultiEdit + tool: Write|Edit|MultiEdit|NotebookEdit # ANTHROPIC_BASE_URL (where the agent's model calls go; ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL and - # any other ANTHROPIC__BASE_URL too) anywhere in a Write, Edit or MultiEdit call's arguments, in any - # case: Windows reads an environment variable's name in any case (`set anthropic_base_url=…`). A mention is - # flagged with a setting: the ways to set or remove it are too many to list (an assignment, a settings key, - # os.Setenv, set_var, reg add, a value on the next line, …), and a flag only marks the call + # any other ANTHROPIC__BASE_URL too) anywhere in a Write, Edit, MultiEdit or NotebookEdit call's + # arguments, in any case: Windows reads an environment variable's name in any case (`set anthropic_base_url=…`). + # A mention is flagged with a setting: the ways to set or remove it are too many to list (an assignment, a settings + # key, os.Setenv, set_var, reg add, a value on the next line, …), and a flag only marks the call pattern: '[Aa][Nn][Tt][Hh][Rr][Oo][Pp][Ii][Cc]_([A-Za-z]+_)?[Bb][Aa][Ss][Ee]_[Uu][Rr][Ll]' label: harness_config - id: TK-F017 From 022624fb63cef66992dabe701c2b3c2b3f4fd4ef Mon Sep 17 00:00:00 2001 From: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:40:21 +0530 Subject: [PATCH 3/4] Cursor: a patch with JSON Python can't read stays an unknown tool; Cline's readers in the timing test An ApplyPatch argument that starts with { and that Python's json module can't read (nesting past its recursion limit, an integer past its digit limit) now leaves the whole patch unread: the call keeps its own name, an unknown tool, decided as on main, whatever headers its other arguments hold. The CPU-time test also runs Cline's apply_patch and run_commands here-doc readers, on a line with a run of spaces inside it. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> --- tests/test_agent_hooks.py | 8 +++++--- tests/test_signer_policy.py | 7 +++++++ tracekit/agent_hooks.py | 13 ++++++++----- 3 files changed, 20 insertions(+), 8 deletions(-) diff --git a/tests/test_agent_hooks.py b/tests/test_agent_hooks.py index 2c8435002..269b9fbf5 100644 --- a/tests/test_agent_hooks.py +++ b/tests/test_agent_hooks.py @@ -1096,11 +1096,13 @@ def test_one_naming_no_file_is_left_to_the_v1_policy_as_before(self): self.assertEqual(policy.evaluate(v1, mapped, args, "/w")["decision"], "allow") # main's v1 decision def test_a_long_run_of_spaces_takes_linear_time(self): - # the review of #767: trimming with a regex took 4.65 s on a line of 40,000 spaces (OpenCode's too) - line = " " * 40_000 + "x" + # the review of #767: trimming with a regex took 4.65 s on a line of 40,000 spaces (OpenCode's and Cline's too) + line = "a" + " " * 40_000 + "b" start = time.process_time() agent_hooks.tool("cursor", "ApplyPatch", {"patch": f"*** Begin Patch\n*** Update File: a.py\n{line}\n*** End Patch"}) - agent_hooks.tool("opencode", "apply_patch", {"patchText": f"*** Begin Patch\n*** Update File: a.py{line}\n"}) + agent_hooks.tool("opencode", "apply_patch", {"patchText": f"*** Begin Patch\n*** Update File: {line}\n"}) + agent_hooks.tool("cline", "apply_patch", {"input": f"*** Begin Patch\n*** Update File: {line}\n*** End Patch"}) + agent_hooks.tool("cline", "run_commands", {"commands": ["cat < Date: Fri, 13 Nov 2026 06:30:59 +0530 Subject: [PATCH 4/4] Cursor: text that isn't JSON is read as the patch; every path argument of a patch or notebook edit is decided From the review of #767: - An ApplyPatch argument starting with { that isn't JSON (json.JSONDecodeError) no longer leaves the patch unread: Cursor's JSON.parse fails on it too and Cursor reads the text as the patch, so Tracekit does as well. A patch with a "{" note beside it, or a first line of "{", is decided on its files. - ApplyPatch and EditNotebook decide every path argument the input names (file_path, path, target_file, filePath, target_notebook, paths) beside the file the tool reads, as Cursor's other tools already did. - The unknown-tool test decides at runtime which JSON this Python reads: 3.12 and later read nesting 5,000 deep, and the patch is then held as an Edit of the hooks file. - docs/coding-agents.md says so. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com> --- docs/coding-agents.md | 2 +- tests/test_signer_policy.py | 39 +++++++++++++++++++++++++++++++------ tracekit/agent_hooks.py | 20 ++++++++++--------- 3 files changed, 45 insertions(+), 16 deletions(-) diff --git a/docs/coding-agents.md b/docs/coding-agents.md index 3a1b66022..ea4ba215f 100644 --- a/docs/coding-agents.md +++ b/docs/coding-agents.md @@ -154,7 +154,7 @@ payloads and Tracekit's installer; not tested in a live Devin session. | Run id | `session_id` | `conversation_id` | `session_id` | `sessionID` | `session_id` | `session_id` | `session_id` | `session_id` | one task (each prompt, from `TaskStart` to `TaskComplete`), keyed on `sessionContext.rootSessionId` (the CLI's session, which `cline --id` resumes; its subagents' calls are in it too), else `taskId` | | Blocking a call | exit 2 + a reason on stderr (and `permissionDecision: deny`); on Windows exit 0 + the JSON deny, since PowerShell turns 2 into 1 and Codex reads the JSON only at 0 | exit 2 + `{"permission": "deny"}` | exit 2 + `{"decision": "deny"}` | the plugin throws before the tool runs when Tracekit blocks the call (exit 2) or the hook can't decide it (any other exit, or Python can't start) | exit 2 + a reason on stderr, stdout empty (a stray stdout line reads as no decision to goose) | exit 2 + a reason on stderr (Qwen Code ignores stdout at exit 2 and sends stderr to the model); nothing on stdout; on Windows the command ends in `; exit $LASTEXITCODE`, since PowerShell turns 2 into 1 | exit 2 + a reason on stderr and `hookSpecificOutput.permissionDecision: "deny"` | exit 2 + a reason on stderr | `{"cancel": true, "errorMessage": ...}` at exit 0 (Cline reads no exit status); a cancel stops the whole task, not only the call | | Tool call ids | from the harness | from the harness | none: paired by tool and arguments, first in first out | `callID` | `tool_call_id`, from the harness | `tool_use_id`, from the harness | none in documented stdin: paired by tool and arguments, first in first out | none in the documented payload: paired by tool and arguments, first in first out | the CLI's `tool_call.id`; the VS Code extension sends none: paired by tool and arguments, first in first out | -| Tool names | `Bash`; `write_stdin` → `Bash` (`command` = the typed `chars`; current Codex sends no hook for it, so what is typed into a running command isn't decided: [limits](limits.md#signer-and-capture)); `apply_patch` → `Edit` (`paths`: every file the patch adds, updates, deletes or moves to, its file headers read as Codex reads them, indented ones too); `apply_patch` run from the shell stays a `Bash` call, which the v2 coding pack holds for a person (`TK-A034`); MCP as `mcp__server__tool` | `Shell` → `Bash`; `Read`, `Write`, `Grep`; `Delete` → `Edit`, so the file rules read it; Cursor's hook sends an edit by any of its tools as a `Read` and then a `Write` of the whole file ([limits](limits.md#signer-and-capture)); the names its transcripts give its edit tools (3.29: `StrReplace`, `ApplyPatch`, `EditNotebook`; an older prompt's `search_replace`, `write`, `delete_file`, `edit_notebook`) → `Edit`, `Edit` (`paths`: every file a patch header names, in any argument), `NotebookEdit` (path: `target_notebook`), `Edit`, `Write`, `Edit`, `NotebookEdit`, each only with the file its tool reads (a patch with no file header, or a tool without its path, passes under its own name); every path the input names is decided (`file_path`, `path`, `target_file`, `filePath`, `target_notebook`: Cursor doesn't document which its tools read); `MCP:x` → `mcp__cursor__x`; other names pass through, which the policy treats as unknown tools | `run_shell_command` → `Bash`; `read_file` and `read_many_files` → `Read`; `write_file` → `Write`; `replace` → `Edit`; `grep_search` (`search_file_content` in older releases) → `Grep`; `glob`, `list_directory`, `web_fetch`, `google_web_search`; MCP tools, which Gemini CLI names `mcp__`, → `mcp___`; every path a file tool reads is decided, under each release's name for it (`file_path`, `absolute_path`, `dir_path`, `path`, and `read_many_files`' `paths` and `include`); `web_fetch` is decided on every URL its prompt names (`urls`) and on a `url` beside it | `bash` → `Bash`; `read`, `write`, `edit` (path: `filePath`); `apply_patch` (and 1.0's `patch`) → `Edit` (`paths`: every file its headers name, and a path with a `:` also up to it, as OpenCode 1.2 reads it); `batch` (experimental; OpenCode 1.x before 1.4 only: later releases and OpenCode 2 have none) is blocked: OpenCode runs the calls in it without plugin hooks; `glob`, `grep` (path: `path`); `webfetch`, `websearch`, `task`; MCP tools under OpenCode's `_` names, which the policy treats as unknown tools | `shell` → `Bash`; `write` → `Write` (path: `path`); `edit` → `Edit` (path: `path`); `tree` → `LS` (path: `path`); `read_image` → `Read` (path: `source`, not `path`); `__` → `mcp____`; other names pass through unchanged, which the policy treats as unknown tools | `run_shell_command` and `monitor` → `Bash`; `read_file` → `Read` (path: `file_path`, `absolute_path` before 0.13); `write_file` → `Write`; `edit` (and Gemini's `replace`) → `Edit`; `notebook_edit` → `NotebookEdit` (path: `notebook_path`); `grep_search` → `Grep`; `glob`, `list_directory`, `web_fetch`, `web_search`, `todo_write`; `agent` → `Task`; any other tool, MCP tools included, under its own name; file paths as for Gemini CLI; `web_fetch` is decided on its `url` and also on every URL its prompt names (Qwen Code fetches only the `url`) | `Execute` → `Bash`; `Create` → `Write`; `ApplyPatch` → `Edit` (`input`: complete patch; `paths`: all file headers); `FetchUrl` → `WebFetch`; other names, including `mcp__server__tool`, pass through | `exec` → `Bash` (`command` in any case, `\r` read as a line end; denied in the hook with no command, input that isn't an object, or a control character but a tab or line end); `write_to_process` → `Bash` (`command` = its one argument besides `shell_id`, the text it writes, whatever its name: its fields aren't documented; `\r` read as a line end; denied in the hook with any other argument, no text, a control character or a bash history expansion (`!-1`, a `^` starting a line) in the text, or text that sets shell state a later line runs: `fc`, an `alias` definition, a function, `trap`, the `exec` builtin, `PROMPT_COMMAND`, `LD_PRELOAD` …); a name sent twice to any tool, in any case, is denied in the hook; `read` → `Read`; `write` → `Write`; `edit` → `Edit` (each decided on every path under a key ending in `path`, `paths` or `file`, case and `_` ignored, and denied in the hook with none); `apply_patch` → `Edit` (`paths`: all patch file headers and a unified diff's file names; denied in the hook with none); `grep`, `glob`; `webfetch` → `WebFetch` (denied in the hook without a `url`, or with one under another spelling too); `mcp__server__tool` and other names pass through | `run_commands` → `Bash` (`command` for one command, `commands` for several, each decided on its own as Cline runs it in its own shell, a here-doc joined to its delimiter's line; from any shape Cline takes: a list, one command, `{command, args}`, `cmd`); `read_files` → `Read` (`paths`: every file, under `files`, `paths` or `file_paths`); `editor` → `Write` when it sends neither `old_text` nor `insert_line` (it then creates a missing file), else `Edit` (its `path`); `apply_patch` → `Edit` (`paths`: every file the patch names); `fetch_web_content` → `WebFetch` (`urls`: every request's URL); an MCP tool `__` → `mcp____`; a call none of these can be read from is cancelled; the other tools pass under their own names | +| Tool names | `Bash`; `write_stdin` → `Bash` (`command` = the typed `chars`; current Codex sends no hook for it, so what is typed into a running command isn't decided: [limits](limits.md#signer-and-capture)); `apply_patch` → `Edit` (`paths`: every file the patch adds, updates, deletes or moves to, its file headers read as Codex reads them, indented ones too); `apply_patch` run from the shell stays a `Bash` call, which the v2 coding pack holds for a person (`TK-A034`); MCP as `mcp__server__tool` | `Shell` → `Bash`; `Read`, `Write`, `Grep`; `Delete` → `Edit`, so the file rules read it; Cursor's hook sends an edit by any of its tools as a `Read` and then a `Write` of the whole file ([limits](limits.md#signer-and-capture)); the names its transcripts give its edit tools (3.29: `StrReplace`, `ApplyPatch`, `EditNotebook`; an older prompt's `search_replace`, `write`, `delete_file`, `edit_notebook`) → `Edit`, `Edit` (`paths`: every file a patch header names, in any argument), `NotebookEdit` (path: `target_notebook`), `Edit`, `Write`, `Edit`, `NotebookEdit`, each only with the file its tool reads: a patch Tracekit can't read, or a tool without its path, is decided as an unknown tool, as before; every path argument the input names is decided too, a patch's and a notebook edit's included (`file_path`, `path`, `target_file`, `filePath`, `target_notebook`, `paths`: Cursor doesn't document which its tools read); `MCP:x` → `mcp__cursor__x`; other names pass through, which the policy treats as unknown tools | `run_shell_command` → `Bash`; `read_file` and `read_many_files` → `Read`; `write_file` → `Write`; `replace` → `Edit`; `grep_search` (`search_file_content` in older releases) → `Grep`; `glob`, `list_directory`, `web_fetch`, `google_web_search`; MCP tools, which Gemini CLI names `mcp__`, → `mcp___`; every path a file tool reads is decided, under each release's name for it (`file_path`, `absolute_path`, `dir_path`, `path`, and `read_many_files`' `paths` and `include`); `web_fetch` is decided on every URL its prompt names (`urls`) and on a `url` beside it | `bash` → `Bash`; `read`, `write`, `edit` (path: `filePath`); `apply_patch` (and 1.0's `patch`) → `Edit` (`paths`: every file its headers name, and a path with a `:` also up to it, as OpenCode 1.2 reads it); `batch` (experimental; OpenCode 1.x before 1.4 only: later releases and OpenCode 2 have none) is blocked: OpenCode runs the calls in it without plugin hooks; `glob`, `grep` (path: `path`); `webfetch`, `websearch`, `task`; MCP tools under OpenCode's `_` names, which the policy treats as unknown tools | `shell` → `Bash`; `write` → `Write` (path: `path`); `edit` → `Edit` (path: `path`); `tree` → `LS` (path: `path`); `read_image` → `Read` (path: `source`, not `path`); `__` → `mcp____`; other names pass through unchanged, which the policy treats as unknown tools | `run_shell_command` and `monitor` → `Bash`; `read_file` → `Read` (path: `file_path`, `absolute_path` before 0.13); `write_file` → `Write`; `edit` (and Gemini's `replace`) → `Edit`; `notebook_edit` → `NotebookEdit` (path: `notebook_path`); `grep_search` → `Grep`; `glob`, `list_directory`, `web_fetch`, `web_search`, `todo_write`; `agent` → `Task`; any other tool, MCP tools included, under its own name; file paths as for Gemini CLI; `web_fetch` is decided on its `url` and also on every URL its prompt names (Qwen Code fetches only the `url`) | `Execute` → `Bash`; `Create` → `Write`; `ApplyPatch` → `Edit` (`input`: complete patch; `paths`: all file headers); `FetchUrl` → `WebFetch`; other names, including `mcp__server__tool`, pass through | `exec` → `Bash` (`command` in any case, `\r` read as a line end; denied in the hook with no command, input that isn't an object, or a control character but a tab or line end); `write_to_process` → `Bash` (`command` = its one argument besides `shell_id`, the text it writes, whatever its name: its fields aren't documented; `\r` read as a line end; denied in the hook with any other argument, no text, a control character or a bash history expansion (`!-1`, a `^` starting a line) in the text, or text that sets shell state a later line runs: `fc`, an `alias` definition, a function, `trap`, the `exec` builtin, `PROMPT_COMMAND`, `LD_PRELOAD` …); a name sent twice to any tool, in any case, is denied in the hook; `read` → `Read`; `write` → `Write`; `edit` → `Edit` (each decided on every path under a key ending in `path`, `paths` or `file`, case and `_` ignored, and denied in the hook with none); `apply_patch` → `Edit` (`paths`: all patch file headers and a unified diff's file names; denied in the hook with none); `grep`, `glob`; `webfetch` → `WebFetch` (denied in the hook without a `url`, or with one under another spelling too); `mcp__server__tool` and other names pass through | `run_commands` → `Bash` (`command` for one command, `commands` for several, each decided on its own as Cline runs it in its own shell, a here-doc joined to its delimiter's line; from any shape Cline takes: a list, one command, `{command, args}`, `cmd`); `read_files` → `Read` (`paths`: every file, under `files`, `paths` or `file_paths`); `editor` → `Write` when it sends neither `old_text` nor `insert_line` (it then creates a missing file), else `Edit` (its `path`); `apply_patch` → `Edit` (`paths`: every file the patch names); `fetch_web_content` → `WebFetch` (`urls`: every request's URL); an MCP tool `__` → `mcp____`; a call none of these can be read from is cancelled; the other tools pass under their own names | What is the same as Claude Code: the policy gate runs before the tool (deny blocks; ask blocks the call until someone approves it from another terminal, then the agent's retry runs: [held calls](#held-calls-approve-then-retry)), events diff --git a/tests/test_signer_policy.py b/tests/test_signer_policy.py index 20af0558d..a0b3b61fe 100644 --- a/tests/test_signer_policy.py +++ b/tests/test_signer_policy.py @@ -7,7 +7,6 @@ import os import random import shutil -import sys import tempfile import time import tracemalloc @@ -2301,11 +2300,14 @@ def test_cursor_edit_tools_are_decided_as_the_edits_they_are(self): (("ApplyPatch", {"patch": patch}), ("Edit", {"file_path": path})), # Cursor unwraps a JSON {"patch": ...} and reads a header from the line trimmed as JavaScript trims (("ApplyPatch", {"patch": json.dumps({"patch": patch})}), ("Edit", {"file_path": path})), - (("ApplyPatch", {"patch": patch.replace("*** Update", " *** Update"), "path": "/w/a.txt"}), + (("ApplyPatch", {"patch": patch.replace("*** Update", "\ufeff *** Update"), "path": "/w/a.txt"}), ("Edit", {"file_path": path})), # and reads \r and \r\n as line ends (the review of #767: a CR-only patch was decided on no file) (("ApplyPatch", {"patch": patch.replace("\n", "\r")}), ("Edit", {"file_path": path})), (("ApplyPatch", patch.replace("\n", "\r\n")), ("Edit", {"file_path": path})), + # text that isn't JSON is read as the patch it is, as Cursor reads it + (("ApplyPatch", {"patch": patch, "note": "{"}), ("Edit", {"file_path": path})), + (("ApplyPatch", {"patch": "{\n" + patch}), ("Edit", {"file_path": path})), (("EditNotebook", {"target_notebook": path, **cell}), ("NotebookEdit", {"notebook_path": path})), (("edit_notebook", {"target_notebook": path, **cell}), ("NotebookEdit", {"notebook_path": path}))) for pack, engine, e in self.every_pack(): @@ -2333,12 +2335,17 @@ def test_a_cursor_edit_naming_no_file_stays_an_unknown_tool(self): ("write", {"contents": "x"}), ("delete_file", {"path": "/w/a.py"}), ("EditNotebook", {"cell_idx": 0, "new_string": "x"}), ("edit_notebook", {"target_notebook": ["/w/a.ipynb"], "file_path": "/w/a.ipynb"})) - # a JSON object Python's json module can't read (nesting past its recursion limit; an integer past its digit - # limit, where it has one) leaves the whole patch unread, whatever headers its other arguments hold + # a patch Tracekit can't read is decided as an unknown tool, as on main; one this Python reads is held inner = json.dumps("*** Begin Patch\n*** Update File: /home/u/.cursor/hooks.json\n@@\n-a\n+b\n*** End Patch\n") note = "*** Begin Patch\n*** Update File: /w/src/app.py\n@@\n-a\n+b\n*** End Patch\n" - for first in ("[" * 5000 + "]" * 5000,) + ("1" + "0" * 5000,) * hasattr(sys, "get_int_max_str_digits"): - forms += (("ApplyPatch", {"patch": '{"patch": ' + first + ', "patch": ' + inner + "}", "note": note}),) + held = () + for first in ("[" * 5000 + "]" * 5000, "1" + "0" * 5000): + text = '{"patch": ' + first + ', "patch": ' + inner + "}" + try: + json.loads(text) + held += (("ApplyPatch", {"patch": text, "note": note}),) + except (ValueError, RecursionError): + forms += (("ApplyPatch", {"patch": text, "note": note}),) for pack, engine, e in self.every_pack(): for name, ti in forms: with self.subTest(pack=pack, engine=engine, name=name, input=ti): @@ -2347,6 +2354,26 @@ def test_a_cursor_edit_naming_no_file_stays_an_unknown_tool(self): self.assertEqual(mapped, name) self.assertIn("TK-UNKNOWN-TOOL", d["rule_ids"]) self.assertNotEqual(d["verdict"], "allow") + for name, ti in held: + with self.subTest(pack=pack, engine=engine, name=name, held=True): + d = e.decide(*agent_hooks.tool("cursor", name, ti)) + self.assertEqual((d["verdict"] != "allow", "TK-F009" in d["rule_ids"]), (True, True)) + + def test_every_path_argument_of_a_cursor_edit_is_decided(self): + # the review of #767: a path argument beside the file a tool reads was dropped from the decision + from tracekit import agent_hooks + ok = "*** Begin Patch\n*** Update File: /w/src/ok.py\n@@\n-a\n+b\n*** End Patch\n" + for pack, engine, e in self.every_pack(): + for name, ti in (("EditNotebook", {"target_notebook": "/w/src/ok.ipynb", "file_path": "/w/.env"}), + ("edit_notebook", {"target_notebook": "/w/src/ok.ipynb", "path": "/w/.env"}), + ("ApplyPatch", {"patch": ok, "path": "/w/.env"}), + ("ApplyPatch", {"patch": ok, "target_file": "/w/.env"}), + ("ApplyPatch", {"patch": ok, "paths": ["/w/.env"]}), + ("StrReplace", {"path": "/w/src/ok.py", "filePath": "/w/.env", "old_string": "a", + "new_string": "b"})): + with self.subTest(pack=pack, engine=engine, name=name, input=ti): + d = e.decide(*agent_hooks.tool("cursor", name, ti)) + self.assertEqual((d["verdict"], "TK-D005" in d["rule_ids"]), ("deny", True), d) def test_a_notebook_edit_naming_the_model_endpoint_is_flagged(self): # TK-F016 read Write, Edit and MultiEdit only (the review of #767): a notebook cell setting it was not flagged diff --git a/tracekit/agent_hooks.py b/tracekit/agent_hooks.py index fc1f5fdef..3e5202be0 100644 --- a/tracekit/agent_hooks.py +++ b/tracekit/agent_hooks.py @@ -382,6 +382,10 @@ def tool(harness, name, ti): if harness == "cursor": if name.startswith("MCP:"): return "mcp__cursor__" + re.sub(r"[^A-Za-z0-9_-]+", "_", name[4:]), ti + # Cursor doesn't document which of these its tools read: every path they name is decided, so a decoy + # `file_path` beside the `path` a tool reads never replaces it (read before a tool's own file is set below) + paths = [f for f in ti["paths"] if isinstance(f, str)] if isinstance(ti.get("paths"), list) else [] + files = [ti[k] for k in CURSOR_PATH_ARGS if isinstance(ti.get(k), str)] if name == "ApplyPatch": # every file a patch header names, in whichever argument holds it, as Cursor reads it: # a {"patch": ...} in JSON unwrapped, \r and \r\n read as \n, each line trimmed as JavaScript trims it texts, unread = list(_strings(ti)), False @@ -389,15 +393,17 @@ def tool(harness, name, ti): if s.strip(JS_SPACE).startswith("{"): try: j = json.loads(s.strip(JS_SPACE)) - except (ValueError, RecursionError): # JSON Python can't read, though JavaScript may: the patch - unread = True # isn't read at all, and stays an unknown tool + except json.JSONDecodeError: # not JSON: Cursor reads the text as it is + continue + except (ValueError, RecursionError): # JSON Tracekit can't read: decided as an unknown tool, as + unread = True # before break if isinstance(j, dict) and list(j) == ["patch"] and isinstance(j["patch"], str): texts.append(j["patch"]) lines = "\n".join(x.strip(JS_SPACE) for x in re.sub(r"\r\n?", "\n", "\n".join(texts)).split("\n")) - files = [f for f in (g.strip(JS_SPACE) for g in PATCH_FILE.findall(lines)) if f] - if files and not unread: - ti["paths"], ti["file_path"] = files, files[0] + headers = [f for f in (g.strip(JS_SPACE) for g in PATCH_FILE.findall(lines)) if f] + if headers and not unread: + ti["paths"], ti["file_path"] = list(dict.fromkeys(headers + files + paths)), headers[0] return "Edit", ti edit = CURSOR_EDITS.get(name) if edit and not isinstance(ti.get(edit[1]), str): # no file to decide it on: left unmapped (CURSOR_EDITS) @@ -407,10 +413,6 @@ def tool(harness, name, ti): for k in CURSOR_PATH_ARGS[1:]: if k in ti and "file_path" not in ti: ti["file_path"] = ti[k] - # Cursor doesn't document which of these its tools read: every path they name is decided, so a decoy - # `file_path` beside the `path` a tool reads never replaces it - paths = [f for f in ti["paths"] if isinstance(f, str)] if isinstance(ti.get("paths"), list) else [] - files = [ti[k] for k in CURSOR_PATH_ARGS if isinstance(ti.get(k), str)] if any(f not in [ti["file_path"], *paths] for f in files): ti["paths"] = list(dict.fromkeys(files + paths)) return edit[0] if edit else CURSOR_TOOLS.get(name, name), ti