diff --git a/docs/reference/file-formats.md b/docs/reference/file-formats.md index 82b1906bd..1b4d34ee5 100644 --- a/docs/reference/file-formats.md +++ b/docs/reference/file-formats.md @@ -112,7 +112,7 @@ Multiple files can set `root: true` for the same target in project and global mo Hermes Agent accepts native snake-case events under `hermesagent.hooks`: `pre_tool_call`, `post_tool_call`, `transform_terminal_output`, `transform_tool_result`, `transform_llm_output`, `pre_llm_call`, `post_llm_call`, `pre_verify`, `pre_api_request`, `post_api_request`, `api_request_error`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`, `subagent_start`, `subagent_stop`, `pre_gateway_dispatch`, `pre_approval_request`, `post_approval_response`, `kanban_task_claimed`, `kanban_task_completed`, and `kanban_task_blocked`. Rulesync maps shared canonical events first, applies canonical keys from `hermesagent.hooks` next, then applies exact native keys last. An exact native key therefore wins when both forms resolve to the same Hermes event. Native-only events remain under `hermesagent.hooks` on import instead of leaking into other targets. -Hooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Gemini CLI, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`) — both share one event surface, in which `preToolUse`/`postToolUse` become named `tool.execute.before`/`tool.execute.after` hooks, `preCompact` becomes the named `experimental.session.compacting` hook (which receives `(input, output)` and exposes nothing to match on, so a `matcher` on it is dropped), `beforeShellExecution`/`afterShellExecution` also land in those named `tool.execute.*` hooks with an implicit `input.tool === "bash"` gate — OpenCode has no shell-execution lifecycle event (`command.executed`, which earlier Rulesync versions mapped `afterShellExecution` to, is a _slash-command_ event, so the hook never fired on shell commands; regenerate to fix), and matchers on the shell events are dropped with a warning since the named hooks expose no command text, and the rest are `event.type` dispatches — `sessionStart` → `session.created`, `stop` → `session.idle`, `afterFileEdit` → `file.edited`, `permissionRequest` → `permission.asked`, `postCompact` → `session.compacted`, `afterError` → `session.error`, `fileChanged` → `file.watcher.updated`; Amp hooks are emitted as a TypeScript plugin (`.amp/plugins/rulesync-hooks.ts`, or `~/.config/amp/plugins/rulesync-hooks.ts` in global mode) using `session.start`, `tool.call`, `tool.result`, `agent.start`, and `agent.end`; Pi Coding Agent hooks are emitted as a Rulesync-owned TypeScript extension (`.pi/extensions/rulesync-hooks.ts`, or `~/.pi/agent/extensions/rulesync-hooks.ts` in global mode) that subscribes to Pi's snake_case extension events (`sessionStart` → `session_start`, `stop` → `agent_end`, `preToolUse` → `tool_call` with the matcher tested as a regex against the tool name, `preCompact` → `session_before_compact`, `postCompact` → `session_compact`, `postModelInvocation` → `message_end` gated on assistant messages so it runs once per finalized model response) and observes events only — command hooks run but cannot block or mutate Pi events; Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and use `powershell`/`bash` command fields — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli uses a dot-notation (e.g. `session.start`, `tool.error`); Kiro emits hooks into `.kiro/agents/default.json` using Kiro's CLI event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI's). +Hooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Qwen Code, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`) — both share one event surface, in which `preToolUse`/`postToolUse` become named `tool.execute.before`/`tool.execute.after` hooks, `preCompact` becomes the named `experimental.session.compacting` hook (which receives `(input, output)` and exposes nothing to match on, so a `matcher` on it is dropped), `beforeShellExecution`/`afterShellExecution` also land in those named `tool.execute.*` hooks with an implicit `input.tool === "bash"` gate — OpenCode has no shell-execution lifecycle event (`command.executed`, which earlier Rulesync versions mapped `afterShellExecution` to, is a _slash-command_ event, so the hook never fired on shell commands; regenerate to fix), and matchers on the shell events are dropped with a warning since the named hooks expose no command text, and the rest are `event.type` dispatches — `sessionStart` → `session.created`, `stop` → `session.idle`, `afterFileEdit` → `file.edited`, `permissionRequest` → `permission.asked`, `postCompact` → `session.compacted`, `afterError` → `session.error`, `fileChanged` → `file.watcher.updated`; Amp hooks are emitted as a TypeScript plugin (`.amp/plugins/rulesync-hooks.ts`, or `~/.config/amp/plugins/rulesync-hooks.ts` in global mode) using `session.start`, `tool.call`, `tool.result`, `agent.start`, and `agent.end`; Pi Coding Agent hooks are emitted as a Rulesync-owned TypeScript extension (`.pi/extensions/rulesync-hooks.ts`, or `~/.pi/agent/extensions/rulesync-hooks.ts` in global mode) that subscribes to Pi's snake_case extension events (`sessionStart` → `session_start`, `stop` → `agent_end`, `preToolUse` → `tool_call` with the matcher tested as a regex against the tool name, `preCompact` → `session_before_compact`, `postCompact` → `session_compact`, `postModelInvocation` → `message_end` gated on assistant messages so it runs once per finalized model response) and observes events only — command hooks run but cannot block or mutate Pi events; Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and use `powershell`/`bash` command fields — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli uses a dot-notation (e.g. `session.start`, `tool.error`); Kiro emits hooks into `.kiro/agents/default.json` using Kiro's CLI event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI's). Example: @@ -186,55 +186,60 @@ Events present in the shared `hooks` block but unsupported by a given tool are s ### Hook event × tool matrix -| Event | Cursor | Claude Code | OpenCode | Kilo | Copilot | Copilot CLI | Factory Droid | Gemini CLI | Codex CLI | deepagents | Kiro | Antigravity IDE | Antigravity CLI | Devin | AugmentCode | Goose | -| ---------------------- | :----: | :---------: | :------: | :--: | :-----: | :---------: | :-----------: | :--------: | :-------: | :--------: | :--: | :-------------: | :-------------: | :---: | :---------: | :---: | -| `sessionStart` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ | -| `sessionEnd` | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ | -| `beforeSubmitPrompt` | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | -| `preToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | -| `postToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | -| `preModelInvocation` | — | — | — | — | — | — | — | — | — | — | — | ✅ | ✅ | — | — | — | -| `postModelInvocation` | — | — | — | — | — | — | — | — | — | — | — | ✅ | ✅ | — | — | — | -| `postToolUseFailure` | ✅ | ✅ | — | — | — | ✅ | — | — | — | ✅ | — | — | — | — | — | ✅ | -| `stop` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | -| `subagentStart` | ✅ | ✅ | — | — | — | ✅ | — | — | ✅ | — | — | — | — | — | — | — | -| `subagentStop` | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | — | -| `preCompact` | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | -| `postCompact` | — | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | — | — | — | — | — | — | -| `afterFileEdit` | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ | -| `beforeShellExecution` | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ | -| `afterShellExecution` | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ | -| `beforeMCPExecution` | ✅ | — | — | — | — | ✅ | — | — | — | — | — | — | — | ✅ | — | — | -| `afterMCPExecution` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | -| `beforeReadFile` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ | -| `beforeAgentResponse` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | ✅ | — | — | -| `afterAgentResponse` | ✅ | — | — | — | — | — | — | ✅ | — | — | — | — | — | ✅ | — | — | -| `afterAgentThought` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `beforeTabFileRead` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | -| `afterTabFileEdit` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | -| `beforeToolSelection` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | -| `permissionRequest` | — | ✅ | ✅ | ✅ | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — | -| `notification` | — | ✅ | — | — | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | -| `setup` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `worktreeCreate` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | -| `worktreeRemove` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `workspaceOpen` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `messageDisplay` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `afterError` | — | — | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | -| `instructionsLoaded` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `userPromptExpansion` | — | ✅ | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | -| `postToolBatch` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `permissionDenied` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `taskCreated` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `taskCompleted` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `stopFailure` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `teammateIdle` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `configChange` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `cwdChanged` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `fileChanged` | — | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | -| `directoryAdded` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `elicitation` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | -| `elicitationResult` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | + + +| Event | Amp | Claude Code | Claude Code plugin | Codex CLI | GitHub Copilot | GitHub Copilot CLI | Goose | Hermes Agent | Grok CLI | Cursor | deepagents-cli | Factory Droid | OpenCode | Kilo Code | Kimi Code | Vibe Code | Qwen Code | Reasonix | Kiro ⚠️ | Kiro CLI | Kiro IDE | Google Antigravity IDE | Google Antigravity CLI | Google Antigravity plugin | JetBrains Junie | AugmentCode | Devin Desktop | Pi Coding Agent | +| ---------------------- | :-: | :---------: | :----------------: | :-------: | :------------: | :----------------: | :---: | :----------: | :------: | :----: | :------------: | :-----------: | :------: | :-------: | :-------: | :-------: | :-------: | :------: | :-----: | :------: | :------: | :--------------------: | :--------------------: | :-----------------------: | :-------------: | :---------: | :-----------: | :-------------: | +| `sessionStart` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ | ✅ | ✅ | +| `sessionEnd` | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | ✅ | — | ✅ | ✅ | ✅ | ✅ | — | — | — | — | ✅ | ✅ | ✅ | ✅ | +| `preToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `postToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | +| `preModelInvocation` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | ✅ | ✅ | — | — | — | ✅ | +| `postModelInvocation` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | ✅ | ✅ | ✅ | — | — | — | ✅ | +| `beforeSubmitPrompt` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | — | — | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ | ✅ | ✅ | +| `stop` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `subagentStop` | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | ✅ | — | — | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | +| `preCompact` | — | ✅ | ✅ | ✅ | — | ✅ | — | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | +| `postCompact` | — | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | — | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | — | — | — | ✅ | ✅ | +| `contextOffload` | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `postToolUseFailure` | — | ✅ | ✅ | — | — | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | — | — | ✅ | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `subagentStart` | — | ✅ | ✅ | ✅ | — | ✅ | — | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `beforeShellExecution` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `afterShellExecution` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `beforeMCPExecution` | — | — | — | — | — | ✅ | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `afterMCPExecution` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `beforeReadFile` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `afterFileEdit` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `afterAgentResponse` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `afterAgentThought` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `beforeTabFileRead` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `afterTabFileEdit` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `permissionRequest` | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | ✅ | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | — | ✅ | — | ✅ | — | +| `notification` | — | ✅ | ✅ | — | — | ✅ | — | — | ✅ | — | ✅ | ✅ | — | — | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | ✅ | — | — | +| `setup` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `afterError` | — | — | — | — | ✅ | ✅ | — | — | — | — | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `worktreeCreate` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `worktreeRemove` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `workspaceOpen` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `messageDisplay` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `todoCreated` | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `todoCompleted` | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `stopFailure` | — | ✅ | ✅ | — | — | — | — | — | ✅ | — | — | — | — | — | ✅ | — | ✅ | — | — | — | — | — | — | — | ✅ | — | — | — | +| `instructionsLoaded` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `userPromptExpansion` | — | ✅ | ✅ | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `postToolBatch` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `permissionDenied` | — | ✅ | ✅ | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | +| `taskCreated` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `taskCompleted` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `teammateIdle` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `configChange` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `cwdChanged` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `fileChanged` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `directoryAdded` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `elicitation` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | +| `elicitationResult` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | + + > **Note:** `beforeSubmitPrompt`, `stop`, `worktreeCreate`, `worktreeRemove`, `messageDisplay`, `postToolBatch`, `taskCreated`, `taskCompleted`, `teammateIdle`, and `cwdChanged` are the Claude Code events the [matcher table](https://code.claude.com/docs/en/hooks) lists as not supporting the `matcher` field (they fire on every occurrence). A matcher authored on one of them is dropped with a warning rather than written into `settings.json` to be ignored. `directoryAdded` is treated the same way for now: the event is announced in the 2.1.219 changelog but has no row in the docs' event table yet, so its matcher support is unknown. diff --git a/package.json b/package.json index 68163693e..e40144661 100644 --- a/package.json +++ b/package.json @@ -47,7 +47,7 @@ "scripts": { "build": "tsdown", "check": "pnpm run fmt:check && pnpm run oxlint && pnpm run typecheck", - "check:docs-content": "pnpm run generate:docs-content && git diff --exit-code src/generated/docs-content.ts", + "check:docs-content": "pnpm run generate:docs-content && git diff --exit-code src/generated/docs-content.ts docs/reference/file-formats.md", "check:gitignore": "pnpm run dev gitignore && git diff --exit-code .gitignore .gitattributes", "check:supported-tools": "tsx scripts/generate-supported-tools-tables.ts && git diff --exit-code README.md docs/reference/supported-tools.md", "check:sync-skill-docs": "tsx scripts/check-skill-docs-sync.ts", diff --git a/scripts/generate-docs-content.ts b/scripts/generate-docs-content.ts index 612829e7f..1fb3954ec 100644 --- a/scripts/generate-docs-content.ts +++ b/scripts/generate-docs-content.ts @@ -4,6 +4,8 @@ import { join, relative, sep } from "node:path"; import { globbySync } from "globby"; +import { renderHookEventsMatrix } from "./hook-events-table.js"; + /** * Embed the canonical `docs/**\/*.md` hierarchy into a generated TypeScript * module so the `rulesync docs` command can serve it from every distribution @@ -14,6 +16,26 @@ const repoRoot = join(import.meta.dirname, ".."); const docsRoot = join(repoRoot, "docs"); const outputPath = join(repoRoot, "src", "generated", "docs-content.ts"); +// Normalize to the repo's formatter so the drift check compares stable output. +// npx is npx.cmd on Windows; a shell resolves it. stderr is inherited so a +// formatter failure stays diagnosable. +const runOxfmt = (path: string): void => { + execFileSync("npx", ["oxfmt", relative(repoRoot, path)], { + cwd: repoRoot, + stdio: ["ignore", "ignore", "inherit"], + shell: process.platform === "win32", + }); +}; + +// Regenerate the derived hook-event matrix inside file-formats.md before +// embedding, so a stale committed table fails the docs-content drift check +// (`check:docs-content` diffs this file as well as the embed). Written +// unconditionally: the renderer emits cells without column padding and oxfmt +// owns the final column layout, mirroring generate-supported-tools-tables.ts. +const hookMatrixPath = join(docsRoot, "reference", "file-formats.md"); +writeFileSync(hookMatrixPath, renderHookEventsMatrix(readFileSync(hookMatrixPath, "utf8")), "utf8"); +runOxfmt(hookMatrixPath); + const filePaths = globbySync("**/*.md", { cwd: docsRoot, // The VitePress internals and the landing page (theme-config frontmatter, @@ -46,12 +68,6 @@ const lines: string[] = [ ]; writeFileSync(outputPath, lines.join("\n"), "utf8"); -// Normalize to the repo's formatter so the drift check compares stable output. -execFileSync("npx", ["oxfmt", relative(repoRoot, outputPath)], { - cwd: repoRoot, - stdio: "ignore", - // npx is npx.cmd on Windows; a shell resolves it. - shell: process.platform === "win32", -}); +runOxfmt(outputPath); // oxlint-disable-next-line no-console console.log(`Embedded ${entries.length} docs into ${relative(repoRoot, outputPath)}`); diff --git a/scripts/generate-supported-tools-tables.ts b/scripts/generate-supported-tools-tables.ts index e19d24350..ada549dcf 100644 --- a/scripts/generate-supported-tools-tables.ts +++ b/scripts/generate-supported-tools-tables.ts @@ -6,6 +6,7 @@ import { getProcessorRegistryEntry, PROCESSOR_REGISTRY } from "../src/types/proc import { TOOL_DISPLAY, type ToolDisplayEntry } from "../src/types/tool-display.js"; import { ALL_TOOL_TARGETS, type ToolTarget } from "../src/types/tool-targets.js"; import { formatError } from "../src/utils/error.js"; +import { replaceBetweenMarkers } from "./markdown-markers.js"; const FEATURES = [ "rules", @@ -104,25 +105,18 @@ const README_AI_MARK = "SUPPORTED_TOOLS_AI"; const README_STD_MARK = "SUPPORTED_TOOLS_STANDARD"; const DOCS_MARK = "SUPPORTED_TOOLS_DOCS"; -const replaceBetween = (content: string, marker: string, body: string): string => { - const begin = ``; - const end = ``; - const startIdx = content.indexOf(begin); - const endIdx = content.indexOf(end); - if (startIdx === -1 || endIdx === -1) { - throw new Error(`Markers ${marker} not found; add ${begin} / ${end} around the table.`); - } - return `${content.slice(0, startIdx + begin.length)}\n${body}\n${content.slice(endIdx)}`; -}; - const renderReadme = (content: string): string => { const ai = buildReadmeTable(TOOL_DISPLAY.filter((e) => e.group === "ai")); const std = buildReadmeTable(TOOL_DISPLAY.filter((e) => e.group === "standard")); - return replaceBetween(replaceBetween(content, README_AI_MARK, ai), README_STD_MARK, std); + return replaceBetweenMarkers( + replaceBetweenMarkers(content, README_AI_MARK, ai), + README_STD_MARK, + std, + ); }; const renderDocs = (content: string): string => - replaceBetween(content, DOCS_MARK, buildDocsTable()); + replaceBetweenMarkers(content, DOCS_MARK, buildDocsTable()); const main = (): void => { // Display list must cover exactly the non-legacy targets. diff --git a/scripts/hook-events-table.test.ts b/scripts/hook-events-table.test.ts new file mode 100644 index 000000000..e045b7917 --- /dev/null +++ b/scripts/hook-events-table.test.ts @@ -0,0 +1,80 @@ +import { describe, expect, it } from "vitest"; + +import { toolHooksFactories } from "../src/features/hooks/hooks-processor.js"; +import { HOOK_EVENTS } from "../src/types/hooks.js"; +import { TOOL_DISPLAY } from "../src/types/tool-display.js"; +import { renderHookEventsMatrix } from "./hook-events-table.js"; +import { replaceBetweenMarkers } from "./markdown-markers.js"; + +const wrap = (inner: string): string => + `before\n\n${inner}\n\nafter`; + +describe("renderHookEventsMatrix", () => { + it("replaces the content between the markers with the generated table", () => { + const result = renderHookEventsMatrix(wrap("| stale |")); + + expect(result).not.toContain("| stale |"); + expect(result.startsWith("before\n\n| Event |")).toBe(true); + expect(result.endsWith("\nafter")).toBe(true); + }); + + it("renders one column per hooks target and one row per supported event", () => { + const result = renderHookEventsMatrix(wrap("")); + const tableLines = result + .split("\n") + .filter((line) => line.startsWith("|")) + .filter((line) => !line.startsWith("| ---")); + + const header = tableLines[0]!; + const headerLabels = header + .split("|") + .map((cell) => cell.trim()) + .filter(Boolean) + .slice(1); + const hooksLabels = TOOL_DISPLAY.filter((entry) => + toolHooksFactories.has(entry.key as never), + ).map((entry) => entry.label); + expect(headerLabels).toEqual(hooksLabels); + + const supportedEventCount = HOOK_EVENTS.filter((event) => + [...toolHooksFactories.values()].some((factory) => factory.supportedEvents.includes(event)), + ).length; + expect(tableLines.length - 1).toBe(supportedEventCount); + }); + + it("marks each cell from the factory's supportedEvents", () => { + const result = renderHookEventsMatrix(wrap("")); + const columns = TOOL_DISPLAY.filter((entry) => toolHooksFactories.has(entry.key as never)); + const rows = result + .split("\n") + .filter((line) => line.startsWith("| `")) + .map((line) => { + const cells = line + .split("|") + .map((cell) => cell.trim()) + .filter(Boolean); + return { event: cells[0]!.replaceAll("`", ""), cells: cells.slice(1) }; + }); + + for (const { event, cells } of rows) { + cells.forEach((cell, index) => { + const factory = toolHooksFactories.get(columns[index]!.key as never)!; + const expected = factory.supportedEvents.includes(event as never) ? "✅" : "—"; + expect(cell, `${event} × ${columns[index]!.label}`).toBe(expected); + }); + } + }); + + it("throws when the markers are missing", () => { + expect(() => renderHookEventsMatrix("no markers here")).toThrow( + "Markers HOOK_EVENTS_MATRIX not found", + ); + }); +}); + +describe("replaceBetweenMarkers", () => { + it("throws when END precedes BEGIN instead of duplicating content", () => { + const content = "\nmiddle\n"; + expect(() => replaceBetweenMarkers(content, "M", "body")).toThrow("Markers M not found"); + }); +}); diff --git a/scripts/hook-events-table.ts b/scripts/hook-events-table.ts new file mode 100644 index 000000000..0367aeab8 --- /dev/null +++ b/scripts/hook-events-table.ts @@ -0,0 +1,50 @@ +import { toolHooksFactories } from "../src/features/hooks/hooks-processor.js"; +import { HOOK_EVENTS, type HookEvent } from "../src/types/hooks.js"; +import { TOOL_DISPLAY } from "../src/types/tool-display.js"; +import { replaceBetweenMarkers } from "./markdown-markers.js"; + +const MARKER = "HOOK_EVENTS_MATRIX"; + +/** + * Render the `Hook event × tool matrix` table in `docs/reference/file-formats.md` + * from each hooks factory's `supportedEvents`, so the table cannot drift from + * `src/types/hooks.ts` (it used to be hand-maintained and was missing columns + * for several hook-capable targets — and still listed removed ones). + * + * Freshness is enforced indirectly: `scripts/generate-docs-content.ts` calls + * this before embedding the docs, so a stale committed table makes + * `pnpm run check:docs-content` fail on the regenerated embed. + */ +export const renderHookEventsMatrix = (content: string): string => { + const factories: ReadonlyMap = + toolHooksFactories; + + // Column order follows TOOL_DISPLAY (the order the other generated tables + // use), restricted to targets that have a hooks factory. + const columns = TOOL_DISPLAY.filter((entry) => factories.has(entry.key)); + const displayedKeys = new Set(columns.map((entry) => entry.key)); + const missing = [...factories.keys()].filter((key) => !displayedKeys.has(key)); + if (missing.length > 0) { + throw new Error(`Hooks targets missing from TOOL_DISPLAY: ${missing.join(", ")}`); + } + + const supportedSets = new Map>( + columns.map((entry) => [entry.key, new Set(factories.get(entry.key)!.supportedEvents)]), + ); + + // Only events at least one hooks target supports get a row, in the canonical + // HOOK_EVENTS order. + const rows = HOOK_EVENTS.filter((event) => + columns.some((entry) => supportedSets.get(entry.key)!.has(event)), + ); + + const header = `| Event | ${columns.map((entry) => entry.label).join(" | ")} |`; + const separator = `| --- | ${columns.map(() => ":-:").join(" | ")} |`; + const body = rows.map((event) => { + const cells = columns.map((entry) => (supportedSets.get(entry.key)!.has(event) ? "✅" : "—")); + return `| \`${event}\` | ${cells.join(" | ")} |`; + }); + const table = [header, separator, ...body].join("\n"); + + return replaceBetweenMarkers(content, MARKER, table); +}; diff --git a/scripts/markdown-markers.ts b/scripts/markdown-markers.ts new file mode 100644 index 000000000..f096b3191 --- /dev/null +++ b/scripts/markdown-markers.ts @@ -0,0 +1,15 @@ +/** + * Replace the content between `` / `` + * comments with a generated body. Shared by the marker-based table generators + * (supported-tools tables, hook-event matrix). + */ +export const replaceBetweenMarkers = (content: string, marker: string, body: string): string => { + const begin = ``; + const end = ``; + const startIdx = content.indexOf(begin); + const endIdx = content.indexOf(end); + if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) { + throw new Error(`Markers ${marker} not found; add ${begin} / ${end} around the table.`); + } + return `${content.slice(0, startIdx + begin.length)}\n${body}\n${content.slice(endIdx)}`; +}; diff --git a/src/generated/docs-content.ts b/src/generated/docs-content.ts index 6f4abdc38..6770be4e8 100644 --- a/src/generated/docs-content.ts +++ b/src/generated/docs-content.ts @@ -38,7 +38,7 @@ export const DOCS_CONTENT: Record = { "reference/command-syntax": '# Command Syntax\n\nSlash commands authored under `.rulesync/commands/*.md` use a **universal syntax** that mirrors Claude Code\'s command placeholders. When rulesync generates a tool-specific command file, it rewrites these placeholders into the syntax that the target tool understands. The reverse rewrite happens on import, so a rulesync ↔ tool round-trip preserves the original universal form.\n\n## Universal placeholders\n\n| Placeholder | Meaning |\n| ------------ | ------------------------------------------------------------------------ |\n| `$ARGUMENTS` | The full argument string the user supplied when invoking the command. |\n| `` !`cmd` `` | Inline shell expansion. The agent runs `cmd` and substitutes its output. |\n\nThese are written exactly as Claude Code accepts them, so writing a rulesync command body is the same as writing a Claude Code command body.\n\n## Per-tool translation\n\nThe table below shows how each placeholder is translated for the supported tools. "pass-through" means the placeholder is emitted verbatim because the target tool already understands the universal form.\n\n| Tool | `$ARGUMENTS` | `` !`cmd` `` |\n| ----------------- | ---------------------- | --------------------------- |\n| Claude Code | pass-through | pass-through |\n| Codex CLI[^codex] | pass-through (literal) | pass-through (literal) |\n| Pi | pass-through | pass-through (literal)[^pi] |\n| Other tools[^1] | pass-through (literal) | pass-through (literal) |\n\n[^1]: Tools not listed do not have a documented translation; their command body is emitted as-is.\n\n[^codex]: Codex CLI prompt files are forwarded to the LLM verbatim; the placeholders are passed to the model as literal text rather than being substituted by the engine.\n\n[^pi]: Pi natively expands `$ARGUMENTS` (along with `$1`, `$2`, `$@`), so `$ARGUMENTS` is a real pass-through there. rulesync still emits `` !`cmd` `` verbatim for Pi, but does not assume Pi expands inline shell snippets — treat that placeholder as literal text on Pi\'s side.\n\nThe translation also runs in reverse when you import an existing tool command file via `rulesync import`, so a tool-native placeholder is rewritten back to the universal form in the generated `.rulesync/commands/*.md`.\n\n## Example\n\nGiven the following rulesync command:\n\n```md\n---\ntargets: ["claudecode"]\ndescription: "Summarize git diff"\n---\n\nSummarize the diff:\n!`git diff`\n\nFocus on $ARGUMENTS.\n```\n\nrulesync generates `.claude/commands/summarize.md`, passing the placeholders through verbatim because Claude Code already understands the universal form.\n\n## Notes\n\n- If you author a command with explicit tool-specific syntax (e.g. you write a tool-native placeholder directly in a rulesync command body), rulesync does **not** re-translate the already-tool-native form. Stick to the universal placeholders to keep commands portable across tools.\n- The translation is purely textual and is applied to the entire body. It does not skip fenced or inline code blocks, so ` ```js\\n$ARGUMENTS\\n``` ` in a rulesync body will still be rewritten when generating tool output. There is **no escape syntax** for the universal placeholders — backslashes are not consumed by the regex, so `\\$ARGUMENTS` is rewritten alongside the placeholder rather than producing a literal `$ARGUMENTS`.\n- The shell expansion regex matches a single backtick-delimited segment without embedded backticks or newlines (`` !`...` ``). Multi-line shell snippets are not supported, and a backtick inside the command body is not allowed.\n', "reference/file-formats": - '# File Formats\n\n## Symlinks\n\nRulesync follows symbolic links when it discovers source files, whether you use a plain `.rulesync/` directory or a separate `--input-root`. Glob-based discovery (rules, commands, subagents, skills) follows symlinked files and directories; single fixed-path files such as `.rulesyncignore`, `.rulesync/mcp.jsonc`, and `.rulesync/permissions.jsonc` are likewise resolved transparently by the OS when read. A symlink inside the input tree that points elsewhere is followed transparently, and the resolved file content is copied into the generated output. This is intentional: it lets you centralize shared skills or rules in one place and reference them via symlinks without duplication (see [issue #1707](https://github.com/dyoshikawa/rulesync/issues/1707)).\n\nThe trust boundary is the directory you point Rulesync at. There is **no** `realpath`-based containment check on individual symlinks, so a link may resolve to a target outside the input root — enforcing containment would break the shared-file use case above. Only run Rulesync against trees you control. Directory symlink **cycles** are handled safely: results are deduplicated by real path, so a cycle does not produce duplicated output. Note that the remote-fetch path (`rulesync fetch` from a Git repository) is a separate, hardened code path that **skips** symlinks entirely, so untrusted remote content never has its symlinks followed.\n\nOne discovery pass is deliberately excluded from the follow-symlinks rule: the scan for nested `AGENTS.md` files (see the `agentsmd` note below). Unlike every other glob above, it walks the whole project rather than a rulesync-owned directory, so a symlink committed to a repository you cloned could otherwise pull a file from outside the project into version-controlled `.rulesync/`. That scan does not follow symlinks.\n\n## `rulesync/rules/*.md`\n\nExample:\n\n```md\n---\nroot: true # true for root-level rules, false for details such as `.agents/memories/*.md`\nlocalRoot: false # (optional, default: false) true for project-specific local rules. Claude Code: CLAUDE.local.md; Rovodev (Rovo Dev CLI) and Roo Code: AGENTS.local.md; Qwen Code: .qwen/QWEN.local.md; Others: append to root file. See the localRoot note below for import behavior\ntargets: ["*"] # * = all, or specific tools\ndescription: "Rulesync project overview and development guidelines for unified AI rules management CLI tool"\nglobs: ["**/*"] # file patterns to match (e.g., ["*.md", "*.txt"])\nagentsmd: # agentsmd and codexcli specific parameters\n # Support for using nested AGENTS.md files for subprojects in a large monorepo.\n # This option is available only if root is false.\n # If subprojectPath is provided, the file is located in `${subprojectPath}/AGENTS.md`.\n # If subprojectPath is not provided and root is false, the file is located in `.agents/memories/*.md`.\n subprojectPath: "path/to/subproject"\ncursor: # cursor specific parameters\n alwaysApply: true\n description: "Rulesync project overview and development guidelines for unified AI rules management CLI tool"\n globs: ["*"]\ncopilot: # copilot specific parameters (non-root `*.instructions.md` files only)\n name: "TypeScript Style" # (optional) display name shown in the VS Code UI; defaults to the file name\n excludeAgent: "code-review" # (optional) "code-review" or "cloud-agent": skip this file for that agent\nantigravity: # antigravity specific parameters\n trigger: "always_on" # always_on, glob, manual, or model_decision\n globs: ["**/*"] # (optional) file patterns to match when trigger is "glob"\n description: "When to apply this rule" # (optional) used with "model_decision" trigger\ndevin: # devin (Devin Desktop, formerly Windsurf) specific parameters\n trigger: "always_on" # always_on, glob, manual, or model_decision\n globs: ["**/*"] # (optional) file patterns to match when trigger is "glob"\n description: "When to apply this rule" # (optional) used with "model_decision" trigger\naugmentcode: # augmentcode specific parameters\n type: "always_apply" # always_apply, manual, or agent_requested\n description: "When to apply this rule" # (optional) used with "agent_requested" type\nkiro: # kiro specific parameters (steering inclusion)\n inclusion: "fileMatch" # always, fileMatch, manual, or auto\n fileMatchPattern: ["src/components/**/*.tsx"] # (optional) glob string or array of globs, used when inclusion is "fileMatch"\n name: "api-design" # (optional) required when inclusion is "auto"; the steering entry key\n description: "REST API design patterns. Use when creating or modifying API endpoints." # (optional) required when inclusion is "auto"; Kiro auto-includes the file when a request matches this\ntakt: # takt specific parameters (optional; emitted under .takt/facets/policies/ — frontmatter is dropped on emit)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\n extends: "base" # (optional) emit a leading `{extends:}` facet-inheritance directive (Takt 0.39.0+)\n facet: "output-contracts" # (optional) "policies" (default) or "output-contracts": redirect this rule to Takt\'s output-structure/report-template facet\n---\n\n# Rulesync Project Overview\n\nThis is Rulesync, a Node.js CLI tool that automatically generates configuration files for various AI development tools from unified AI rule files. The project enables teams to maintain consistent AI coding assistant rules across multiple tools.\n\n...\n```\n\nMultiple files can set `root: true` for the same target in project and global modes. Rulesync renders each file through the target adapter, then combines compatible root or plain-Markdown single-file outputs in deterministic source-discovery order with one blank line between fragments. Local rules are ordered lexicographically by source file path and composed before non-overridden `.curated/` rules, which are also ordered lexicographically; filename prefixes such as `10-` and `20-` control composition order within each set. Targets that map source rules to distinct native paths keep those files separate. Explicitly supported plain-Markdown modular rules that normalize to the same output path are combined; a fragment whose generated output carries its own frontmatter block (such as Amp\'s `globs:` gate) is never composed and stays a separate file instead. Unsafe collisions involving a source `root: true` rule fail. Other exact or case-insensitive modular collisions remain separate and produce a warning that the last write wins wherever the filesystem treats their paths as the same.\n\n> **localRoot import note:** For the tools that emit a separate personal local file (Claude Code and its legacy layout: `CLAUDE.local.md`; Rovodev and Roo Code: `AGENTS.local.md`; Qwen Code: `.qwen/QWEN.local.md`), `rulesync import` also reads that file back as a `localRoot: true` rule under `.rulesync/rules/`, keeping the tool-side basename. The imported rule\'s `targets` is scoped to the tool it was imported from, not `"*"` — a wildcard would spread the personal content into other tools\' committed root files on the next generate (tools without a separate local file append `localRoot` bodies to their root file), and importing from several tools would otherwise produce conflicting wildcard `localRoot` rules. Widen `targets` by hand if you do want the content shared. The same scoping applies to `rulesync convert`: converting to a different tool drops the source tool\'s personal local file rather than folding it into the destination\'s root file. The derived `.gitignore` covers the imported copy via `.rulesync/rules/*.local.md`; run `rulesync gitignore` after a first import if the project\'s `.gitignore` has not been generated yet, so the personal content stays untracked. Project scope only, like `localRoot` generation itself.\n\n> **AGENTS.md standard note (`agentsmd`):** Nested `AGENTS.md` files are the standard\'s only scoping mechanism — agents read the nearest file in the directory tree, so the closest one wins. Rulesync writes them from `agentsmd.subprojectPath` and, on **import**, discovers them by scanning the project for `**/AGENTS.md`. Hidden directories (other tools\' generated output, including rulesync\'s own) are skipped at any depth, as are `node_modules/` and `__pycache__/`. Build, vendoring and scratch directories (`vendor/`, `third_party/`, `dist/`, `build/`, `out/`, `target/`, `coverage/`, `tmp/`, `temp/`, `venv/`) are skipped **at the project root only**, because a top-level `build/` is a build directory while `packages/build/` is a real subproject. Beyond those names, the scan honors your `.gitignore`: a file git does not track is not your project\'s source, and copying a vendored dependency\'s rule file into version-controlled `.rulesync/rules/` would hand third-party instructions to every tool — including the ones that concatenate non-root rules into a single always-loaded file. (Ignore rules come from the `.gitignore` files at and below the output root — a parent repository\'s rules are not consulted, so running against a subdirectory only sees that subdirectory\'s own. The test is applied to the _directories_ above each file, not the file itself, so the `**/AGENTS.md` entry that `rulesync gitignore` writes for its own output does not disable the scan; the flip side is that ignoring one individual `AGENTS.md` no longer keeps it out of the import.) Symbolic links are not followed, so a link committed to a repository cannot pull a file from outside the project into version-controlled `.rulesync/`. The scan is import-only: a nested file rulesync did not write is never removed by `--delete`. That means deleting the rulesync rule stops the reference from being listed in the root `AGENTS.md`, but leaves the subproject file itself on disk — where agents still read it, since the nearest file wins. Remove it by hand. Each discovered file is imported to `.rulesync/rules/.md` (e.g. `packages/api/AGENTS.md` → `packages-api.md`) carrying `agentsmd.subprojectPath`, so the next generate puts it back where it came from. A subproject that would claim the reserved `overview.md` name gets an `-agents` suffix instead, so the root rule is never overwritten; any other pair of sources deriving the same name is reported at import time, since only the last one survives. Import always rewrites `.rulesync/rules/`, so a subproject whose derived name matches a rule file you wrote by hand replaces it — pick distinct names, or keep hand-written rules out of the derived namespace. See .\n\n> **Kiro note:** Kiro reads steering files from `.kiro/steering/*.md` and uses an `inclusion` frontmatter block to decide when each is loaded (`always`, `fileMatch` with a `fileMatchPattern`, `manual`, or `auto` — which auto-includes the file when a request matches its companion `description`, keyed by `name`). Rulesync derives this for non-root steering files: an explicit `kiro.inclusion` block round-trips as-is (carrying `name`/`description` through for `auto`); otherwise specific (non-wildcard) `globs` map to `inclusion: fileMatch` (a single glob is written as a string and multiple as a YAML array, both of which Kiro accepts), so the rule applies only to matching files instead of always; otherwise the file stays always-on and is written without a frontmatter block (Kiro\'s no-frontmatter default). The root overview index is always written plain so Kiro always loads it. In **global** mode (`--global`), steering is written to `~/.kiro/steering/` with the root rule as `~/.kiro/steering/product.md` (Kiro does not read `~/AGENTS.md`, so the project-scope root `AGENTS.md` is not used at the home level), and global MCP is written to `~/.kiro/settings/mcp.json`.\n\n> **Grok CLI note:** Grok Build writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.grok/AGENTS.md` (global, via `--global`), and non-root rules to `.grok/rules/*.md` (project) / `~/.grok/rules/*.md` (global). Grok scans that directory flat and in name order, alongside the AGENTS.md family — earlier Rulesync versions folded every topic rule into the single root file, which matched Grok 0.2.54 but not the current release, so regenerate to split them back out. Non-root files carry no frontmatter. Because this is a directory Grok defines rather than one Rulesync invented, a project may already have hand-written files there: Rulesync owns it from now on, so `--delete` removes anything in it — `~/.grok/rules/` included, in global mode — that `.rulesync/rules/` does not produce. Move those files into `.rulesync/rules/` first.\n\n> **Kilo Code note:** Kilo writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.kilo/rules/*.md`. Because Kilo v7 does not auto-load files under `.kilo/rules/`, Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `kilo.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under `.kilo/rules/` — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> In global mode (`--global`), Kilo\'s own layout is asymmetric: the root rule goes to `~/.config/kilo/AGENTS.md`, while non-root rules go to `~/.kilo/rules/*.md` — the same `.kilo`-relative path the skills adapter uses in both scopes. Global rules need no `instructions` registration, because Kilo auto-discovers every `~/.kilo/rules/*.md` on config load; writing the files is enough, and no global `kilo.jsonc` is touched by the rules feature.\n\n> **Kimi Code note:** Kimi Code reads `.kimi-code/AGENTS.md` at project scope and `~/.kimi-code/AGENTS.md` at user scope. When `KIMI_CODE_HOME` is set, Rulesync follows Kimi and resolves every global Kimi-specific file (`AGENTS.md`, `mcp.json`, `config.toml`, `skills/`, and `agents/`) under that custom data root; the shared `~/.agents/skills/` and `~/.agents/agents/` discovery roots remain under the user\'s real home directory. Because Kimi has no dedicated directory for topic-based instruction files, Rulesync folds every non-root rule body into that single file. See the [Kimi Code agents and instruction-files docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html) and [environment-variable docs](https://moonshotai.github.io/kimi-code/en/configuration/env-vars.html).\n\n> **OpenCode note:** OpenCode writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.opencode/memories/*.md`. Because OpenCode auto-loads only the root `AGENTS.md` plus files explicitly listed in the `instructions` array of `opencode.json` (it does not auto-discover a rules directory), Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `opencode.json`/`opencode.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). The same applies in **global** mode (via `--global`): OpenCode reads `instructions` from the global `~/.config/opencode/opencode.json` too, so global non-root rules are written to `~/.config/opencode/memories/*.md` and registered there (entries relative to the config file\'s directory, e.g. `memories/style.md`) instead of being dropped. This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under its managed rules directory (`.opencode/memories/`, or `memories/` in the global config) — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> **Qwen Code note:** Qwen Code writes the root rule to the auto-loaded `QWEN.md` (project) / `~/.qwen/QWEN.md` (global, via `--global`) as plain Markdown, and non-root rules to its path-based context-rule directory `.qwen/rules/` (project) / `~/.qwen/rules/` (global). Each non-root rule is a Markdown file with optional YAML frontmatter: Rulesync maps `globs` ⇄ Qwen\'s `paths` (a picomatch glob array) and `description` ⇄ `description`. A rule **with** specific `paths` is _conditional_ — Qwen lazily injects it only when the model touches a matching file — while a rule **without** `paths` (empty or wildcard `**/*`/`*` globs) is a _baseline_ rule loaded at session start and is written as plain Markdown with no frontmatter block. The `.qwen/rules/` directory supersedes the legacy `.qwen/memories/` import surface, so each rule is emitted to exactly one location; the root `QWEN.md` is unchanged. A `localRoot: true` rule is emitted to `.qwen/QWEN.local.md` (project scope only) — Qwen Code v0.16.2\'s personal project context file, loaded after the shared `QWEN.md` so it can override team instructions; the file is covered by the derived `.gitignore` since Qwen Code does not gitignore it for you. See the [Qwen Code memory/context docs](https://github.com/QwenLM/qwen-code).\n\n> **Cline note:** Cline writes the root rule to the auto-loaded `AGENTS.md` (project) as plain Markdown, and non-root rules to its flat `.clinerules/` directory. Each non-root rule is a Markdown file with optional YAML frontmatter for conditional activation: Rulesync maps `globs` ⇄ Cline\'s `paths` (a glob array; the rule loads only when a matching file is in context) and `description` ⇄ `description`. A rule with **specific** `globs` emits `paths`; a rule with **universal** globs (`**/*` or `*`) emits `alwaysApply: true` (always load); a rule **without** globs is written as plain Markdown with no frontmatter block (always active). In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` (Cline CLI v3.0.15+) as plain Markdown, and non-root rules go to `~/Documents/Cline/Rules/*.md` — the global modular-rules directory both the VS Code extension and the SDK/CLI read — with the same conditional-frontmatter conversion project rules get. See the [Cline rules docs](https://docs.cline.bot/customization/cline-rules).\n\n> **Warp note (rules):** Warp reads project rules from the root `AGENTS.md` (or the back-compat `WARP.md`) and does not scan a modular rules directory, so non-root rule bodies are folded into the single root `./AGENTS.md`. In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` — Warp\'s third rule source alongside project and Warp Drive rules, also used from remote hosts in SSH sessions — with the same folding. Other targets (e.g. Cline) own the same global path; as with the shared project-root `AGENTS.md`, each target regenerates the file per its own semantics. See the [Warp rules docs](https://docs.warp.dev/agent-platform/capabilities/rules/) and [file locations](https://docs.warp.dev/terminal/settings/file-locations/).\n\n> **Pi note:** Pi writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.pi/agent/AGENTS.md` (global, via `--global`) as plain Markdown, and folds non-root rules into that single file (Pi has no modular rules directory). Pi additionally loads two system-prompt instruction files. `.pi/APPEND_SYSTEM.md` (project) / `~/.pi/agent/APPEND_SYSTEM.md` (global) **appends** to the default system prompt, and Rulesync emits it from any rule that opts in via a `pi.systemPrompt: append` frontmatter block — those rule bodies are routed to `APPEND_SYSTEM.md` instead of `AGENTS.md`, multiple opted-in rules concatenate in source order, and the file is managed by generate/import/delete like the root file (note: if you hand-authored `.pi/APPEND_SYSTEM.md` before this feature existed, `generate --delete` for the `pi` target now treats it as a managed path and removes it unless a rule opts in — import it first to convert it into a canonical rule). The opt-in is ignored on the `root: true` rule, which always stays on `AGENTS.md` (routing the root away would leave the context file without a merge target). `.pi/SYSTEM.md` (project) / `~/.pi/agent/SYSTEM.md` (global) **replaces** the default system prompt entirely — which silently disables Pi\'s built-in tool instructions — so Rulesync deliberately never emits it and leaves it to be authored by hand. Example:\n>\n> ```yaml\n> ---\n> targets: ["pi"]\n> description: "House style for the system prompt"\n> pi:\n> systemPrompt: append # routes this rule\'s body to .pi/APPEND_SYSTEM.md / ~/.pi/agent/APPEND_SYSTEM.md\n> ---\n> ```\n>\n> See the [Pi usage docs](https://pi.dev/docs/latest/usage).\n\n> **Devin note:** The root rule is emitted to the project-root `AGENTS.md` — the file [Devin CLI / Devin Local actually reads](https://docs.devin.ai/cli/extensibility/rules) (its rules page does not list `.devin/rules/` among its sources) — as plain markdown, while non-root rules keep going to `.devin/rules/*.md`, the Devin Desktop Cascade directory whose `trigger` activation modes (`always_on`, `glob`, `manual`, `model_decision`) are driven by the `devin` frontmatter block. Global mode is unchanged (`~/.config/devin/AGENTS.md`).\n\n> **Amp note:** Amp gates an @-mentioned guidance file on `globs:` YAML frontmatter — the file is loaded only after Amp has read a file matching one of the globs, and **without** the frontmatter it is always loaded. Rulesync therefore emits each non-root rule\'s `globs` as that frontmatter on the generated `.agents/memories/*.md` file (in addition to the advisory `applyTo` value in the root file\'s TOON table, which Amp does not enforce), and restores it into the canonical `globs` on import. Amp implicitly prefixes each glob with `**/` unless it starts with `./` or `../`, so canonical globs pass through verbatim. See [Globs in AGENTS.md](https://ampcode.com/news/globs-in-AGENTS.md).\n\n> **Junie note:** Junie CLI resolves project guidelines **first-match-wins** — `.junie/AGENTS.md` → root `AGENTS.md` → the legacy `.junie/guidelines.md` / `.junie/guidelines/` — and documents no file-inclusion mechanism, so Rulesync writes the root rule to `.junie/AGENTS.md` (project) / `~/.junie/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file. The legacy `.junie/guidelines.md` is still accepted as an import fallback. Earlier Rulesync versions emitted non-root rules to `.junie/memories/*.md`, which is not a documented Junie read path; those files are no longer generated (stale outputs stay gitignored but are not cleaned up automatically). See the [Junie guidelines docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html).\n\n> **Reasonix note:** Reasonix auto-injects a hierarchical instruction document, reading its vendor-specific `REASONIX.md` (alongside the cross-tool `AGENTS.md`/`CLAUDE.md`) by walking user-home → ancestors → project root/local. Rulesync writes the vendor `REASONIX.md` at the project root (project) / `~/.reasonix/REASONIX.md` (global, via `--global`) and folds non-root rules into that single file, since Reasonix has no modular rules directory. Directory-scoped rules are the exception: Context Engine v2 (v1.18.0) also walks from the workspace root to the target path loading per-directory instruction files (“Deeper directories beat broader directories”), so a non-root rule carrying `agentsmd.subprojectPath` is emitted as a nested `/REASONIX.md` (project scope only) instead of being folded — its paragraphs load only under that path rather than being carried on every turn. On **import**, nested `REASONIX.md` files are discovered by the same project scan the AGENTS.md standard uses (same dependency/build-directory exclusions; import-only, never removed by `--delete`) and land in `.rulesync/rules/-reasonix.md` with `targets: ["reasonix"]` and the `subprojectPath` carried, so the next generate puts them back. The `-reasonix` suffix and the reasonix-only targeting keep them from clobbering the AGENTS.md standard\'s derived names or surprising other tools with new nested files; note that a rule targeting both `agentsmd` and `reasonix` with a `subprojectPath` produces a nested `AGENTS.md` **and** a nested `REASONIX.md` in the same directory, both of which Reasonix loads — scope such rules to one target. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md) and [Context Engine v2 docs](https://github.com/esengine/DeepSeek-Reasonix/blob/v1.18.0/docs/SESSION_MEMORY_RETRIEVAL.md).\n\n## `.rulesync/hooks.jsonc`\n\n`.rulesync/hooks.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/hooks.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nHermes Agent accepts native snake-case events under `hermesagent.hooks`: `pre_tool_call`, `post_tool_call`, `transform_terminal_output`, `transform_tool_result`, `transform_llm_output`, `pre_llm_call`, `post_llm_call`, `pre_verify`, `pre_api_request`, `post_api_request`, `api_request_error`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`, `subagent_start`, `subagent_stop`, `pre_gateway_dispatch`, `pre_approval_request`, `post_approval_response`, `kanban_task_claimed`, `kanban_task_completed`, and `kanban_task_blocked`. Rulesync maps shared canonical events first, applies canonical keys from `hermesagent.hooks` next, then applies exact native keys last. An exact native key therefore wins when both forms resolve to the same Hermes event. Native-only events remain under `hermesagent.hooks` on import instead of leaking into other targets.\n\nHooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Gemini CLI, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`) — both share one event surface, in which `preToolUse`/`postToolUse` become named `tool.execute.before`/`tool.execute.after` hooks, `preCompact` becomes the named `experimental.session.compacting` hook (which receives `(input, output)` and exposes nothing to match on, so a `matcher` on it is dropped), `beforeShellExecution`/`afterShellExecution` also land in those named `tool.execute.*` hooks with an implicit `input.tool === "bash"` gate — OpenCode has no shell-execution lifecycle event (`command.executed`, which earlier Rulesync versions mapped `afterShellExecution` to, is a _slash-command_ event, so the hook never fired on shell commands; regenerate to fix), and matchers on the shell events are dropped with a warning since the named hooks expose no command text, and the rest are `event.type` dispatches — `sessionStart` → `session.created`, `stop` → `session.idle`, `afterFileEdit` → `file.edited`, `permissionRequest` → `permission.asked`, `postCompact` → `session.compacted`, `afterError` → `session.error`, `fileChanged` → `file.watcher.updated`; Amp hooks are emitted as a TypeScript plugin (`.amp/plugins/rulesync-hooks.ts`, or `~/.config/amp/plugins/rulesync-hooks.ts` in global mode) using `session.start`, `tool.call`, `tool.result`, `agent.start`, and `agent.end`; Pi Coding Agent hooks are emitted as a Rulesync-owned TypeScript extension (`.pi/extensions/rulesync-hooks.ts`, or `~/.pi/agent/extensions/rulesync-hooks.ts` in global mode) that subscribes to Pi\'s snake_case extension events (`sessionStart` → `session_start`, `stop` → `agent_end`, `preToolUse` → `tool_call` with the matcher tested as a regex against the tool name, `preCompact` → `session_before_compact`, `postCompact` → `session_compact`, `postModelInvocation` → `message_end` gated on assistant messages so it runs once per finalized model response) and observes events only — command hooks run but cannot block or mutate Pi events; Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and use `powershell`/`bash` command fields — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli uses a dot-notation (e.g. `session.start`, `tool.error`); Kiro emits hooks into `.kiro/agents/default.json` using Kiro\'s CLI event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI\'s).\n\nExample:\n\n```json\n{\n "version": 1,\n "hooks": {\n "sessionStart": [{ "type": "command", "command": ".rulesync/hooks/session-start.sh" }],\n "preToolUse": [{ "matcher": "Bash", "command": ".rulesync/hooks/confirm.sh" }],\n "postToolUse": [{ "matcher": "Write|Edit", "command": ".rulesync/hooks/format.sh" }],\n "stop": [{ "command": ".rulesync/hooks/audit.sh" }]\n },\n "cursor": {\n "hooks": {\n "afterFileEdit": [{ "command": ".cursor/hooks/format.sh" }]\n }\n },\n "claudecode": {\n "hooks": {\n "notification": [\n {\n "matcher": "permission_prompt",\n "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh"\n }\n ]\n }\n },\n "opencode": {\n "hooks": {\n "afterShellExecution": [{ "command": ".rulesync/hooks/post-shell.sh" }]\n }\n },\n "copilot": {\n "hooks": {\n "afterError": [{ "command": ".rulesync/hooks/report-error.sh" }]\n }\n }\n}\n```\n\n**Top-level keys:**\n\n- `version`: Schema version (currently `1`).\n- `hooks`: Map of canonical event names to an array of hook entries. These are dispatched to every tool that supports the given event.\n- `amp.hooks`, `cursor.hooks`, `claudecode.hooks`, `opencode.hooks`, `kilo.hooks`, `copilot.hooks`, `copilotcli.hooks`, `factorydroid.hooks`, `codexcli.hooks`, `goose.hooks`, `deepagents.hooks`, `kiro.hooks`, `kiro-ide.hooks`, `qwencode.hooks`, `grokcli.hooks`: Tool-specific **override keys**. Entries under these keys are emitted only for the corresponding tool, so tool-only events (e.g. `afterFileEdit` for Cursor/OpenCode/Kilo, `worktreeCreate` for Claude Code, `afterError` for Copilot/Copilot CLI, `PostFileSave`/`PreTaskExec` for Kiro IDE) can coexist with shared ones without leaking to other tools. `copilotcli.hooks` falls back to `copilot.hooks`, which in turn falls back to the shared `hooks` block.\n\n**Hook entry keys:**\n\n- `command` (required): Shell command to execute when the event fires.\n- `type` (optional): One of `"command"` (default), `"prompt"`, `"http"`, `"agent"`, `"mcp_tool"`, or `"function"` — the union of the hook types accepted across supported tools. Each tool supports a subset (most support only `command`); hooks with a type a tool does not support are skipped for that tool with a warning. See notes below.\n- `matcher` (optional): Regex used by tools that scope hooks to specific tool names (e.g. `preToolUse`, `postToolUse`, `notification`). Ignored by events that do not take a matcher (e.g. `sessionStart`, `worktreeCreate`, `worktreeRemove`).\n- `timeout` (optional): Per-hook timeout in seconds, forwarded to tools that support it.\n- `cacheTtl` (optional): Number of seconds to cache a successful hook result. Forwarded to Kiro CLI as `cache_ttl_seconds`; `0` disables caching and Kiro never caches `AgentSpawn` hooks.\n- `failClosed` (optional): Boolean. When `true`, a hook failure (crash, timeout, invalid JSON) blocks the action instead of allowing it through. Passed through to Cursor\'s `.cursor/hooks.json` and to JetBrains Junie\'s `~/.junie/config.json` (as Junie\'s equivalently-named `blockOnError` flag).\n- `async` (optional): Boolean. When `true`, the hook command runs in the background without blocking. Forwarded to Qwen Code (`.qwen/settings.json`) and JetBrains Junie (`~/.junie/config.json`, same field name).\n- `shell` (optional): Either `"bash"` or `"powershell"` — the only two interpreter values any tool accepts. Forwarded to Qwen Code and Claude Code command hooks. Like `args`, `async` and `asyncRewake`, it is documented on command hooks only, so it is not emitted on a hook of another type.\n- `url` / `headers` / `allowedEnvVars` (optional, `http` hooks): the POST target URL, request headers (values support `$VAR` interpolation), and the env-var allowlist for that interpolation. Forwarded to Claude Code and Qwen Code http hooks.\n- `server` / `tool` / `input` (optional, `mcp_tool` hooks): the configured MCP server name, the tool to call on it, and the (arbitrary JSON) arguments, whose string values support `${path}` substitution from the hook input. Forwarded to Claude Code mcp_tool hooks.\n- `model` (optional, `prompt` / `agent` hooks): the model used for evaluation (defaults to a fast model). Forwarded to Claude Code prompt/agent hooks and to Qwen Code prompt hooks.\n- `args` (optional, `command` hooks): an argument list. When present — an empty list counts, and is the form the Claude Code docs use — the tool spawns `command` directly as an executable with these arguments. There is no shell, so Rulesync writes the project-directory prefix as the braced placeholder `${CLAUDE_PROJECT_DIR}/…` that Claude Code substitutes itself, rather than the quoted shell form. Forwarded to Claude Code and AugmentCode. Only `command` is prefixed; entries of `args` are passed through exactly as written.\n- `asyncRewake` (optional): boolean. Like `async`, but wakes Claude when the hook exits with code 2. Forwarded to Claude Code command hooks.\n- `once` (optional): boolean. Run the hook once per session, then remove it. Forwarded to Claude Code (honored in skill frontmatter; accepted but ignored in settings files) and Qwen Code http hooks.\n- `continueOnBlock` (optional): boolean. Feed a blocking hook\'s rejection reason back to the model and continue the turn instead of ending it. Forwarded to Claude Code.\n- `commandWindows` (optional): a Windows-only override for `command`, so one hook set can be cross-platform. Forwarded to Codex CLI command hooks (`.codex/hooks.json`), which is the only tool that accepts it.\n- `statusMessage` (optional): the progress text shown while the hook runs. Forwarded to Qwen Code (command and http hooks) and to Codex CLI command hooks.\n- `if` (optional): a single permission rule (same syntax as `settings.json` permission rules, e.g. `"Bash(rm *)"`) that filters a hook by tool arguments in addition to the tool name. Forwarded to Claude Code, where it is evaluated only on tool events (`preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `permissionDenied`); it round-trips as an opaque string.\n\nTop-level `hooks` keys must be canonical event names; unknown event names are rejected at parse time. Tool-specific override blocks (e.g. `kiro-ide.hooks`) additionally accept tool-native event keys, which pass through verbatim.\n\nEvents present in the shared `hooks` block but unsupported by a given tool are skipped for that tool (a warning is logged at generate time). The canonical `notification` event maps to deepagents-cli\'s `input.required` (human-in-the-loop interrupt).\n\n### Hook event × tool matrix\n\n| Event | Cursor | Claude Code | OpenCode | Kilo | Copilot | Copilot CLI | Factory Droid | Gemini CLI | Codex CLI | deepagents | Kiro | Antigravity IDE | Antigravity CLI | Devin | AugmentCode | Goose |\n| ---------------------- | :----: | :---------: | :------: | :--: | :-----: | :---------: | :-----------: | :--------: | :-------: | :--------: | :--: | :-------------: | :-------------: | :---: | :---------: | :---: |\n| `sessionStart` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ |\n| `sessionEnd` | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ |\n| `beforeSubmitPrompt` | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ |\n| `preToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |\n| `postToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |\n| `preModelInvocation` | — | — | — | — | — | — | — | — | — | — | — | ✅ | ✅ | — | — | — |\n| `postModelInvocation` | — | — | — | — | — | — | — | — | — | — | — | ✅ | ✅ | — | — | — |\n| `postToolUseFailure` | ✅ | ✅ | — | — | — | ✅ | — | — | — | ✅ | — | — | — | — | — | ✅ |\n| `stop` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |\n| `subagentStart` | ✅ | ✅ | — | — | — | ✅ | — | — | ✅ | — | — | — | — | — | — | — |\n| `subagentStop` | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | — |\n| `preCompact` | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — |\n| `postCompact` | — | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | — | — | — | — | — | — |\n| `afterFileEdit` | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ |\n| `beforeShellExecution` | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ |\n| `afterShellExecution` | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ |\n| `beforeMCPExecution` | ✅ | — | — | — | — | ✅ | — | — | — | — | — | — | — | ✅ | — | — |\n| `afterMCPExecution` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — |\n| `beforeReadFile` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | ✅ |\n| `beforeAgentResponse` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | ✅ | — | — |\n| `afterAgentResponse` | ✅ | — | — | — | — | — | — | ✅ | — | — | — | — | — | ✅ | — | — |\n| `afterAgentThought` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `beforeTabFileRead` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — |\n| `afterTabFileEdit` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — |\n| `beforeToolSelection` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — |\n| `permissionRequest` | — | ✅ | ✅ | ✅ | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — |\n| `notification` | — | ✅ | — | — | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — |\n| `setup` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `worktreeCreate` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — |\n| `worktreeRemove` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `workspaceOpen` | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `messageDisplay` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterError` | — | — | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — |\n| `instructionsLoaded` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `userPromptExpansion` | — | ✅ | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — |\n| `postToolBatch` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `permissionDenied` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `taskCreated` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `taskCompleted` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `stopFailure` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `teammateIdle` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `configChange` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `cwdChanged` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `fileChanged` | — | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — |\n| `directoryAdded` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `elicitation` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `elicitationResult` | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n\n> **Note:** `beforeSubmitPrompt`, `stop`, `worktreeCreate`, `worktreeRemove`, `messageDisplay`, `postToolBatch`, `taskCreated`, `taskCompleted`, `teammateIdle`, and `cwdChanged` are the Claude Code events the [matcher table](https://code.claude.com/docs/en/hooks) lists as not supporting the `matcher` field (they fire on every occurrence). A matcher authored on one of them is dropped with a warning rather than written into `settings.json` to be ignored. `directoryAdded` is treated the same way for now: the event is announced in the 2.1.219 changelog but has no row in the docs\' event table yet, so its matcher support is unknown.\n\n> **Note:** Rulesync implements OpenCode hooks as a plugin at `.opencode/plugins/rulesync-hooks.js` and Kilo hooks as a plugin at `.kilo/plugins/rulesync-hooks.js`, so importing from OpenCode/Kilo to rulesync is not supported. Both only support command-type hooks (not prompt-type).\n\n> **Note:** Rulesync implements Amp hooks as a generated TypeScript plugin at `.amp/plugins/rulesync-hooks.ts` (project) or `~/.config/amp/plugins/rulesync-hooks.ts` (global), so importing arbitrary Amp plugin code is not supported. Amp supports command hooks for `sessionStart` → `session.start`, `preToolUse` → `tool.call`, `postToolUse` → `tool.result`, `beforeSubmitPrompt` → `agent.start`, and `stop` → `agent.end`. Tool-event matchers are regular expressions against the Amp tool name; definitions with a matcher on any lifecycle event are skipped with a warning. A failing `preToolUse` command rejects the tool call and lets the agent continue; other mapped events observe the command result.\n\n> **Amp command syntax:** Amp executes plugin commands with [Bun Shell](https://bun.com/docs/runtime/shell), whose syntax differs slightly from POSIX shells. Use `$VAR` for environment expansion (`${VAR}` remains literal) and `$(command)` for command substitution (backticks remain literal). Rulesync passes the authored command through unchanged so quoting and escaped operators retain their Bun Shell meaning.\n\n> **Note:** GitHub Copilot\'s format uses separate `powershell` and `bash` fields for hooks. Rulesync supports only a single `command` field and resolves this by emitting the command under the `powershell` key on Windows, and under the `bash` key on all other platforms.\n\n> **Note:** Hook file paths per tool:\n>\n> - **Copilot (cloud agent / VS Code)** — project: `/.github/hooks/copilot-hooks.json`; global: `~/.copilot/hooks/copilot-ide-hooks.json`. VS Code and the coding agent both document `~/.copilot/hooks` as the user scope and load every `*.json` in that folder; the Copilot CLI\'s global file already occupies `copilot-hooks.json` there, so the VS Code target uses a distinct filename and the two never overwrite each other. Note the flip side of "every `*.json` is loaded": generating **both** `copilot` and `copilotcli` in global mode leaves two files in that one folder, and a reader of the folder runs the hooks from both — so a command present in your canonical config fires twice per event. Generate only one of the two globally unless you want that.\n> - **Copilot CLI** — project: `/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`, `userPromptTransformed` ← `userPromptExpansion`, `preMcpToolCall` ← `beforeMCPExecution`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`; on import the portable `command` field is read as the cross-platform fallback when neither shell field is present, and `timeout` is honored as an alias for `timeoutSec` when `timeoutSec` is absent. On generate the canonical `shell` selector chooses `bash` or `powershell`; without it the portable `command` field is written, so the generated file does not depend on the machine Rulesync ran on), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). An entry\'s optional `matcher` field is emitted and round-tripped on the six events the hooks reference documents as matcher-aware — `preToolUse` and `postToolUse` (regex on the tool name), `permissionRequest` (tool name), `notification` (notification type), `preCompact` (the trigger, `manual` or `auto`) and `subagentStart` (agent name); on any other event a matcher is dropped with a warning because the CLI does not honor it there. See the [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference).\n> - **Antigravity IDE / Antigravity CLI** — project: `/.agents/hooks.json`; global: `~/.gemini/config/hooks.json`. Both targets share the same dedicated `hooks.json` (a Claude-Code-style matcher map nested under a generated `rulesync` hook name), so enabling both writes the same file.\n> - **Devin Desktop (formerly Windsurf)** — project: `/.windsurf/hooks.json`; global: `~/.codeium/windsurf/hooks.json`. The Cascade Hooks file location is unchanged by the Devin Desktop rebrand.\n> - **AugmentCode** — project: `/.augment/settings.json`; global: `~/.augment/settings.json`. Hooks are merged under the top-level `hooks` key of the shared settings file (which also holds `toolPermissions`).\n> - **Kimi Code** — global only: `~/.kimi-code/config.toml`. Hooks are merged into the shared `[[hooks]]` array without replacing unrelated model, provider, or permission settings.\n> - **Vibe Code** — project: `/.vibe/hooks.toml`; global: `~/.vibe/hooks.toml`. Stable since v2.21.0, which removed the `enable_experimental_hooks` flag: declaring a hook is enough, so Rulesync writes nothing into `.vibe/config.toml` for hooks.\n\n> **Note:** Because each AI tool evolves its own hook surface at its own pace, the matrix above reflects the events Rulesync currently translates. When a tool ships a new event that Rulesync does not yet support, the most reliable path is to open an issue — the matrix is the intended baseline to compare against.\n\n> **Note:** Kiro hooks are emitted into `.kiro/agents/default.json` under the `hooks` field, merging with any existing agent configuration (tools, allowedTools, etc.). Both `sessionEnd` and `stop` canonical events map to Kiro CLI\'s `stop` event. Only `command`-type hooks are supported; `prompt`-type hooks are silently skipped. Kiro CLI uses `timeout_ms` (in milliseconds) for per-hook timeouts and `cache_ttl_seconds` for successful-result caching; Rulesync maps the latter to the canonical `cacheTtl` field in both directions.\n\n> **Note:** Antigravity (IDE and CLI) writes a dedicated `hooks.json` keyed by a **named hook** whose value holds the event map, e.g. `{ "rulesync": { "PreToolUse": [ { "matcher": "...", "hooks": [...] } ], "Stop": [ { "hooks": [...] } ] } }`. Rulesync emits a single generated hook under the stable name `rulesync`. It supports five lifecycle events — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `preModelInvocation` ⇄ `PreInvocation`, `postModelInvocation` ⇄ `PostInvocation`, and `stop` ⇄ `Stop` — where `PreInvocation`/`PostInvocation`/`Stop` are matcher-less handler lists. On import, both the named-hook wrapper and a legacy flat top-level event map are accepted, and the optional per-hook `enabled` flag is ignored.\n\n> **Note:** Devin Desktop (formerly Windsurf) Cascade Hooks (GA) are written to a dedicated `hooks.json` whose top-level `hooks` key maps each Cascade event name to a **flat array** of hook objects (no `matcher`, no `type`, no inner `hooks` wrapper, and no `timeout`). Each object carries `command` and/or `powershell`, plus optional `show_output` and `working_directory`. Rulesync splits the generic tool lifecycle into Devin\'s file/command/MCP-specific events, so the canonical events map bijectively: `beforeReadFile` ⇄ `pre_read_code`, `beforeTabFileRead` ⇄ `post_read_code`, `afterTabFileEdit` ⇄ `pre_write_code`, `afterFileEdit` ⇄ `post_write_code`, `beforeShellExecution` ⇄ `pre_run_command`, `afterShellExecution` ⇄ `post_run_command`, `beforeMCPExecution` ⇄ `pre_mcp_tool_use`, `afterMCPExecution` ⇄ `post_mcp_tool_use`, `beforeSubmitPrompt` ⇄ `pre_user_prompt`, `afterAgentResponse` ⇄ `post_cascade_response`, `beforeAgentResponse` ⇄ `post_cascade_response_with_transcript`, and `worktreeCreate` ⇄ `post_setup_worktree`. Canonical events with no Devin equivalent (e.g. `sessionStart`, `stop`) are dropped with a logged warning. The Cascade Hooks file location (`.windsurf/hooks.json` / `~/.codeium/windsurf/hooks.json`) is retained from the Windsurf era and is unaffected by the rebrand.\n\n> **Note:** AugmentCode (Auggie CLI) hooks are merged under the top-level `hooks` key of the shared `.augment/settings.json` (project) / `~/.augment/settings.json` (global), mirroring Claude Code\'s per-event matcher arrays (`{ "EventName": [ { "matcher": "...", "hooks": [ { "type": "command", "command": "...", "timeout": ... } ] } ] }`). The `hooks` block is merged in place so it coexists with the `toolPermissions` block from the permissions feature. Seven lifecycle events are supported — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `notification` ⇄ `Notification`, and `beforeSubmitPrompt` ⇄ `PromptSubmit` (added in Auggie 0.27.0). The `matcher` field (a case-sensitive regex, default `.*`, with `mcp:*` support) applies only to the tool events `PreToolUse`/`PostToolUse`; any matcher on the session events (including `Notification` and `PromptSubmit`) is dropped with a logged warning. Two Auggie-specific fields round-trip as well: a command hook\'s `args` (extra argv the runner appends, authored as `args` on the canonical hook) and the matcher group\'s `metadata` (`includeConversationData` / `includeMCPMetadata` / `includeUserContext`, which select what the runner puts in the JSON payload the script receives). `metadata` belongs to the group upstream, so it is authored on any hook of the group and re-applied to every hook of that group on import. Both matter because the `hooks` key is owned in the shared settings file: a value not written here is erased from a hand-written `settings.json` on the next generate. Commands are emitted verbatim — Auggie exposes `AUGMENT_PROJECT_DIR` as a runtime environment variable, not as an inline command substitution, so no directory prefix is added. Only `command`-type hooks are supported. On **import** (project scope), Rulesync also reads the layered overrides file `/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before importing, following Auggie\'s documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including the `hooks` events — are combined across tiers), so personal hook overrides are picked up without dropping base events. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json`, AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode.\n\n> **Note:** Vibe Code (mistral-vibe) hooks are written to a dedicated `.vibe/hooks.toml` (project) / `~/.vibe/hooks.toml` (global) as a flat `[[hooks]]` TOML array. Each entry carries its own event `type`, a `command`, and optional `name`, `timeout` (seconds, default 60), and `description`. Tool-hook entries (`pre_tool` / `post_tool`) additionally carry a tool-name `match` (an fnmatch glob like `bash`/`mcp_*` or a `re:`-prefixed regex, case-insensitive — the canonical `matcher` field; `*` means "any tool") and an optional `strict` flag; `post_agent` carries neither. Three events are supported — `preToolUse` ⇄ `pre_tool`, `postToolUse` ⇄ `post_tool`, and `stop` ⇄ `post_agent` (fires after every assistant turn that ends without pending tool calls). Only `command`-type hooks are emitted. Vibe v2.21.0 graduated hooks from experimental: it renamed all three types (`before_tool` → `pre_tool`, `after_tool` → `post_tool`, `post_agent_turn` → `post_agent`) and removed the `enable_experimental_hooks` flag, so declaring a hook is enough and Rulesync no longer writes an auxiliary `.vibe/config.toml`. `HookType` is a strict enum upstream, so an entry using an old name is rejected outright.\n\n> **Note:** Goose hooks follow the Open Plugins spec: Rulesync writes a plugin directory `hooks/hooks.json` that Goose auto-discovers at startup. Locations are `/.agents/plugins/rulesync/hooks/hooks.json` (project) and `~/.agents/plugins/rulesync/hooks/hooks.json` (global). The JSON shape matches Claude Code\'s (`{ "hooks": { "EventName": [ { "matcher": "...", "hooks": [ { "type": "command", "command": "..." } ] } ] } }`). Eleven lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `beforeReadFile` ⇄ `BeforeReadFile`, `afterFileEdit` ⇄ `AfterFileEdit`, `beforeShellExecution` ⇄ `BeforeShellExecution`, and `afterShellExecution` ⇄ `AfterShellExecution` — matching Goose\'s `HookEvent` enum exactly (it has no `SubagentStart`/`SubagentStop`). The `matcher` regex is preserved, commands are emitted verbatim (Goose exposes `PLUGIN_ROOT` as a runtime environment variable), and only `command`-type hooks are supported.\n\n> **Note:** Qwen Code hooks are written under the top-level `hooks` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global), using Claude-style PascalCase per-matcher arrays (`{ "EventName": [ { "matcher": "...", "sequential": false, "hooks": [ { "type": "command", "command": "...", "timeout": ... } ] } ] }`). Qwen\'s supported event set **differs from Gemini CLI\'s**, so rulesync defines a Qwen-specific mapping. Twenty-one lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `postToolBatch` ⇄ `PostToolBatch`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `userPromptExpansion` ⇄ `UserPromptExpansion`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, `postCompact` ⇄ `PostCompact`, `permissionRequest` ⇄ `PermissionRequest`, `permissionDenied` ⇄ `PermissionDenied`, `notification` ⇄ `Notification`, `instructionsLoaded` ⇄ `InstructionsLoaded`, `todoCreated` ⇄ `TodoCreated`, `todoCompleted` ⇄ `TodoCompleted`, and `messageDisplay` ⇄ `MessageDisplay` (fires repeatedly as the reply streams; added in Qwen Code v0.19.10). Commands are emitted verbatim (no `$GEMINI_PROJECT_DIR` rewriting). Qwen\'s four hook types are supported: `command`, `prompt` (which carries the required `prompt` body — with `$ARGUMENTS` interpolation — and an optional `model` override, both round-tripped; a prompt hook without a `prompt` is warned about at generate time since Qwen Code loads it and fails it at runtime), `http` (which carries a `url` and POSTs JSON to it; the type and URL round-trip), and `function`. Per-hook fields added in [Qwen Code PR #2827](https://github.com/QwenLM/qwen-code/pull/2827) round-trip as well: command hooks carry `async` (run in the background), `env` (extra subprocess environment variables), and `shell` (`bash`/`powershell`); http hooks carry `headers` (with `${VAR}` interpolation), `allowedEnvVars` (the env-var allowlist), and `once` (single execution per event per session); `statusMessage` (progress text) applies to both. Command-only fields are emitted only on command hooks and http-only fields only on http hooks. The group-level `sequential` flag (parallel by default) and the top-level `disableAllHooks` switch are both round-tripped, and other top-level keys in `settings.json` are preserved. See the [Qwen Code hooks docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/hooks.md).\n\n> **Note:** Reasonix hooks are written to a dedicated `.reasonix/settings.json` (project) / `~/.reasonix/settings.json` (global) — a Claude-Code-style but standalone JSON file, separate from the `[permissions]`/`[[plugins]]` TOML config. Unlike Claude Code, each event key maps directly to a **flat array** of hook objects (no `matcher`/`hooks` wrapper): `{ "EventName": [ { "match": "...", "command": "...", "description": "...", "timeout": ... } ] }`. All ten of Reasonix\'s documented events are mapped — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `stop` ⇄ `Stop`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `subagentStop` ⇄ `SubagentStop`, `postModelInvocation` ⇄ `PostLLMCall`, `notification` ⇄ `Notification`, and `preCompact` ⇄ `PreCompact`. `match` (Reasonix\'s matcher field name) is honored only on `PreToolUse`/`PostToolUse`; a matcher on any other event is dropped with a warning. The canonical `timeout` field is documented in seconds, while Reasonix\'s `timeout` is milliseconds, so rulesync converts (`× 1000` on generate, `÷ 1000` on import). Only `command`-type hooks are supported. The `settings.json` file is not documented as holding anything besides hooks today, but rulesync merges non-destructively and never deletes it, in case a future Reasonix version adds other keys. See the [Reasonix Hooks guide](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/DESKTOP_HOOKS.zh-CN.md).\n\n> **Note:** Grok CLI (xAI Grok Build) hooks are written to a dedicated, standalone `rulesync.json` that Grok auto-discovers from `.grok/hooks/*.json` (project) / `~/.grok/hooks/*.json` (global). The JSON shape is Claude-Code-compatible: each event nests under the top-level `hooks` key as a per-matcher array (`{ "hooks": { "EventName": [ { "matcher": "...", "hooks": [ { "type": "command", "command": "...", "timeout": ... } ] } ] } }`). All fourteen documented events map 1:1 onto canonical arms — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `permissionDenied` ⇄ `PermissionDenied`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `notification` ⇄ `Notification`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, and `postCompact` ⇄ `PostCompact`. A `matcher` (a regex tested against the tool name) is honored on the tool-name events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionDenied`), matching Claude Code\'s semantics; a matcher on any other event is dropped with a warning. Commands are emitted verbatim (Grok documents no project-directory variable). See the [Grok hooks docs](https://docs.x.ai/build/features/hooks). Both handler types Grok defines round-trip: a `command` hook runs a command, and an `http` hook POSTs the payload to its `url`. Note that a `.rulesync/hooks.*` obtained with `rulesync fetch` can therefore point a Grok hook at any URL — read it before generating.\n\n> **Note:** Kimi Code hooks are global-only and written as flat `[[hooks]]` entries in `~/.kimi-code/config.toml`, with `event`, `command`, and optional `matcher`/`timeout`. Rulesync maps fourteen canonical lifecycle events to Kimi\'s PascalCase names: `sessionStart`, `sessionEnd`, `beforeSubmitPrompt`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `stop`, `stopFailure`, `notification`, `subagentStart`, `subagentStop`, `preCompact`, and `postCompact`. Kimi\'s native `PermissionResult` and `Interrupt` events have no canonical equivalents, but they can be preserved in the `kimi-code.hooks` override. Only `command` hooks are emitted. Kimi normally runs these user-level hooks with each current session project as the working directory, which would let an unrelated repository substitute a relative script or influence commands such as `npm test`. Rulesync therefore wraps every generated command so it first changes to the trusted absolute directory containing the source `.rulesync/hooks.jsonc`; relative paths and project-aware commands consistently resolve against that source rather than whichever repository Kimi later opens. Kimi requires `timeout` to be an integer from 1 to 600 seconds; invalid canonical values are omitted with a warning so Kimi can still load the config. The shared TOML file is merged in place and never deleted. See the [Kimi Code hooks docs](https://moonshotai.github.io/kimi-code/en/customization/hooks.html).\n\n## `.github/mcp.json` and `.copilot/mcp-config.json`\n\nExample:\n\n```json\n{\n "mcpServers": {\n "serena": {\n "type": "stdio",\n "command": "uvx",\n "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"]\n },\n "github": {\n "type": "http",\n "url": "http://localhost:3000/mcp"\n },\n "local-dev": {\n "type": "local",\n "command": "node",\n "args": ["scripts/start-local-mcp.js"]\n }\n }\n}\n```\n\nThis file is used by the GitHub Copilot CLI for MCP server configuration. Rulesync manages it by converting from the unified `.rulesync/mcp.jsonc` format. Both scopes use the same `{ "mcpServers": {...} }` shape but write to different paths:\n\n- **Project mode:** `.github/mcp.json` (relative to project root) — the Copilot CLI auto-loads MCP servers from this workspace config file ([changelog v1.0.61, 2026-06-09](https://github.com/github/copilot-cli)).\n- **Global mode:** `~/.copilot/mcp-config.json` (relative to home directory) — the personal/global MCP configuration.\n\n> **Migration note:** earlier Rulesync versions wrote the **project-mode** Copilot CLI MCP config to `.copilot/mcp-config.json` (the same path used for global mode). Project mode now writes the dedicated workspace file `.github/mcp.json` instead, so a previously generated project-scope `.copilot/mcp-config.json` is no longer managed and can be removed by hand.\n\nRulesync preserves explicit `type` values for `http`, `sse`, and `local` servers. For command-based servers that omit a transport type, Rulesync emits the mandatory `"type": "stdio"` field required by the Copilot CLI. `streamable-http` is written as `http`, the transport it names, and the canonical `httpUrl` alias is normalized to the `url` Copilot CLI reads. A server the Copilot CLI config cannot express is skipped with a warning rather than failing the run: one that declares no transport at all (the shape a Kilo `{"enabled": …}` toggle imports as, which switches off a server some other config layer defines — every entry here defines a server), one that names a remote transport but no `url`/`httpUrl`, one that names a local transport but no `command`, and a `ws` server, since Copilot CLI has no WebSocket transport.\n\n## `rulesync/commands/*.md`\n\nExample:\n\n```md\n---\ndescription: "Review a pull request" # command description\ntargets: ["*"] # * = all, or specific tools\ncopilot: # copilot specific parameters (optional)\n description: "Review a pull request"\n agent: "agent" # (optional) VS Code prompt-file agent: "ask", "agent", "plan", or a custom agent name (replaces the deprecated "mode")\nantigravity: # antigravity specific parameters\n trigger: "/review" # Specific trigger for workflow (renames file to review.md)\n turbo: true # (Optional, default: true) Append // turbo for auto-execution\ntakt: # takt specific parameters (optional; emitted under .takt/facets/instructions/)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\n extends: "base" # (optional) emit a leading `{extends:}` facet-inheritance directive (Takt 0.39.0+)\npi: # pi coding agent specific parameters (optional)\n argument-hint: "[message]" # Hint shown in Pi\'s command palette\ncodexcli: # Codex CLI custom-prompt specific parameters (optional)\n argument-hint: "[message]" # Hint shown for the custom prompt\'s arguments\nroo: # Roo Code specific parameters (optional)\n mode: "architect" # (optional) mode slug to switch to before running the command body (e.g. "code", "architect")\n---\n\ntarget_pr = $ARGUMENTS\n\nIf target_pr is not provided, use the PR of the current branch.\n\nExecute the following in parallel:\n\n...\n```\n\nThe command body itself uses a Claude Code-compatible **universal syntax** (e.g. `$ARGUMENTS`, `` !`cmd` ``). When a target tool expects a different placeholder syntax, rulesync translates it automatically on generation and reverses the translation on import. See [Command Syntax](./command-syntax.md) for the full mapping.\n\n> **Codex CLI deprecation note:** Codex CLI\'s own docs now state "Custom prompts are deprecated. Use skills for reusable instructions" (see [Custom Prompts](https://developers.openai.com/codex/custom-prompts)). Rulesync\'s `codexcli` commands still generate the global-only `~/.codex/prompts/*.md` custom-prompt files described above — they remain functional and no removal date has been announced, so this behavior is unchanged for now. For new reusable instructions, prefer rulesync\'s `codexcli` skills support (see `.rulesync/skills/*/SKILL.md` below) instead.\n\n> **Warp note:** Warp documents skills as its custom slash-command surface — any skill is invocable as `/{skill-name}` with `$ARGUMENTS` / `$ARGUMENTS[N]` / `$N` argument substitution — so rulesync emits each command onto the native skills surface as `.warp/skills//SKILL.md` (project) / `~/.warp/skills//SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. Warp\'s `.warp/workflows/` YAML files are parameterized shell-command templates, not agent prompts, and are deliberately not used. Commands import and `--delete` are no-ops for `warp` because the skills feature owns the `.warp/skills/` tree (importing it as commands would double-import every skill) — mirrors the Devin note below. Keep command and skill names distinct for this target, since a command and a skill sharing a name write the same `SKILL.md` path. See the [Warp skills docs](https://docs.warp.dev/agent-platform/capabilities/skills/).\n\n> **Devin note:** Devin\'s extensibility docs no longer document a standalone workflows/commands component — reusable prompts invoked as slash commands are [Skills](https://docs.devin.ai/cli/extensibility/skills/overview) (`/name`). Rulesync therefore emits each command onto the native skills surface as `.devin/skills//SKILL.md` (project) / `~/.config/devin/skills//SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. The legacy Windsurf/Cascade-era `.devin/workflows/` and `~/.codeium/windsurf/global_workflows/` locations are no longer emitted (stale outputs there stay gitignored but are not cleaned up automatically). Commands import and `--delete` are no-ops for `devin` because the skills feature owns the `.devin/skills/` tree (importing it as commands would double-import every skill). Note that a command and a skill sharing the same name write the same `SKILL.md` path, so keep command and skill names distinct for this target.\n\n> **Agent Skills standard note (`agentsskills`):** Rulesync accepts the legacy rulesync spellings on input but always **emits** the shapes the [specification](https://agentskills.io/specification) requires: `allowed-tools` becomes a space-separated scalar (a YAML list is joined), `compatibility` becomes a string (an object is flattened to `key: value` pairs), and `metadata` values are stringified so the block stays a string→string map. Generation also checks the normative constraints and warns — without failing the run — when `name` is empty, longer than 64 characters, contains anything but lowercase letters, digits and single hyphens, or does not match its parent directory name; when `description` is empty or longer than 1024 characters; when `compatibility` exceeds 500 characters; or when an `allowed-tools` list entry contains whitespace, which the space-separated form cannot represent. These are warnings rather than errors because a conformant client only _skips_ such a skill, and because import stays lenient as the [client-implementation guide](https://agentskills.io/client-implementation/adding-skills-support) advises. A value that normalizes to the empty string (`compatibility: {}`, `allowed-tools: []`) is dropped rather than written, since the spec requires `compatibility` to be 1–500 characters when present. On **import**, `allowed-tools` is normalized back to the canonical rulesync list, so a generate → import round trip leaves `.rulesync/skills/**` in the shape it started in (the `compatibility` and `metadata` coercions are one-way, because the legacy object/number forms have no conformant equivalent). `hermesagent` reads the same `agentsskills` block and applies the same normalization in both directions, so one rulesync source never produces two different on-disk spellings — except for `metadata`, which stays structured there because Hermes reads `metadata.hermes.*` as YAML. A `hermesagent:` override still wins over the shared block (as for every tool-specific section), so a list or mapping written there is emitted as-is and reported as a spec violation rather than rewritten. Validate the result with the spec\'s own [`skills-ref validate`](https://github.com/agentskills/agentskills/tree/main/skills-ref). Import leniency is root-based as well as tool-based: any tool scanning an Agent Skills interop root (project `.agents/skills/`, global `~/.agents/skills/`, or Amp\'s `~/.config/agents/skills/`) skips-and-warns on a skill (directory-form or flat-file) that fails to load there — the cross-vendor directory is where foreign-authored, potentially non-conformant skills live — while each tool\'s own native root (e.g. Rovo Dev\'s `.rovodev/skills/`) stays fail-fast.\n\n> **Replit note:** Replit\'s skills page states conformance to the [Agent Skills specification](https://agentskills.io/specification), so `replit.allowed-tools` accepts either the spec\'s space-separated string or a canonical rulesync list and is always **emitted** as the string; `replit.compatibility` likewise accepts the spec\'s string alongside the legacy object form. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents` — so keep list entries free of whitespace, since the space-separated form cannot represent an entry such as `Bash(git commit:*)` and a client would read it back as two. An object `compatibility` is emitted unchanged rather than flattened: unlike the join, that conversion would be one-way, so the legacy form stays as-is and is simply not spec-conformant on disk.\n\n> **Vibe skills note:** Vibe discovers skills under `.vibe/skills/` (project) and `~/.vibe/skills/` (global), plus the shared `.agents/skills/` root at **both** scopes — Vibe\'s `user_skills_dirs` returns `~/.vibe/skills` and `~/.agents/skills` alike. Rulesync registers the shared root as an import fallback at either scope; it is import-only and is never removed by Vibe-target orphan deletion.\n\n> **Pi skills note:** Pi implements the [Agent Skills specification](https://agentskills.io/specification), so `pi.allowed-tools` accepts either the spec\'s space-delimited string or a canonical rulesync list and is always **emitted** as the string; `pi.compatibility` likewise accepts the spec\'s string alongside the legacy object form. Importing a spec-conformant `SKILL.md` used to fail outright. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents`; keep list entries free of whitespace, since the space-delimited form cannot represent an entry such as `Bash(git commit:*)`. An `allowed-tools` value that normalizes to the empty string (an empty list) is dropped rather than written. An object `compatibility` is emitted unchanged rather than flattened, because that conversion would be one-way.\n\n> **Hermes Agent note:** Commands are global-only and remain distinct from skills. Rulesync writes JSON command specs to `~/.hermes/rulesync/commands/.json`, installs the `rulesync-commands` plugin under `~/.hermes/plugins/`, and enables it in `~/.hermes/config.yaml`. The plugin registers each spec with Hermes\'s [`ctx.register_command()` plugin API](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/) and dispatches the prompt through `delegate_task`; invocation arguments are appended to the prompt. `.rulesync/skills//SKILL.md` still generates a full [Hermes Agent Skill](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/) under `~/.hermes/skills//SKILL.md`, which Hermes also exposes as a dynamic slash command. Rulesync rejects command/skill names that would collide in Hermes\'s slash-command namespace, and rejects nested command paths that flatten to the same name. Generate commands with `rulesync generate --targets hermesagent --features commands --global`.\n>\n> Releases before this native plugin transport emitted Hermes commands as `~/.hermes/skills//SKILL.md`. Rulesync cannot distinguish those files from real user-authored skills safely, so remove an obsolete legacy file manually after confirming that `.rulesync/skills//SKILL.md` does not own it.\n\n> **Qwen Code note:** Custom commands are emitted as **Markdown** files (not TOML — TOML is deprecated upstream) under `.qwen/commands/` (project) and `~/.qwen/commands/` (global, via `--global`). The file is an optional YAML frontmatter block followed by the prompt body; besides `description`, Qwen Code\'s command loader reads `when_to_use` (invocation guidance), `argument-hint` (completion hint), and `disable-model-invocation`, all typed and round-tripped. Subdirectory namespacing is supported: `.qwen/commands/git/commit.md` becomes the `/git:commit` command. Any extra fields are preserved on round-trip under the `qwencode:` block.\n\n> **OpenCode import note:** OpenCode lets commands live both as Markdown files under `.opencode/commands/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `command` key. On import, rulesync reads both: each inline entry\'s `template` becomes the command body and its `description`/`agent`/`model`/`subtask` fields become frontmatter. A Markdown file takes precedence over an inline entry with the same name.\n\n> **AugmentCode note:** Commands are written to `.augment/commands/.md` (project) / `~/.augment/commands/.md` (global, via `--global`). Subdirectories are namespaces — `.augment/commands/git/commit.md` is `/git:commit` — so nested rulesync commands keep their nesting rather than being flattened to a basename. If you generated AugmentCode commands with an earlier Rulesync, the flattened files it wrote are still on disk under their old names; `--delete` removes them. Auggie also discovers commands under the cross-tool `.agents/commands/` root, so **import** reads that root too and treats a command found there as if it lived under `.augment/commands/` — the command\'s name is its path under whichever root it came from. Generation stays on `.augment/commands/`, and `.agents/commands/` is never written to or swept for orphans, since the files there may belong to another tool — Rulesync itself writes that root for the `agentsmd` target, so a command already imported from `.augment/commands/` is not imported again from there under a flattened name. Auggie\'s other shared root, `.claude/commands/`, is deliberately not read: it is Claude Code\'s own output, which Rulesync already imports as that target. Importing from a shared root is announced, because the result is a Rulesync command written for every target on the next generate. See the [custom commands docs](https://docs.augmentcode.com/cli/custom-commands).\n\n> **Reasonix note:** Custom slash commands are Markdown files under `.reasonix/commands/` (project) / `~/.reasonix/commands/` (global, via `--global`) — directly analogous to Claude Code\'s `.claude/commands/`, since Reasonix explicitly mirrors Claude Code\'s conventions. Frontmatter supports `description` and `argument-hint`, and the body uses the same `$ARGUMENTS` / `$1`…`$N` placeholder syntax. Subdirectory namespacing is supported (`git/commit.md` → `/git:commit`). Any extra fields are preserved on round-trip under the `reasonix:` block. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md#slash-commands).\n\n> **Grok CLI note:** Custom slash commands are Markdown files under `.grok/commands/` (project) / `~/.grok/commands/` (global, via `--global`), read by the same Claude-Code-compatible frontmatter parser Grok uses for skills. Rulesync emits `description` plus, from the `grokcli:` block, `argument-hint`, `user-invocable` (default true) and `disable-model-invocation` (default false) — the same invocation-control pair Grok skills honor. Two upstream constraints are worth knowing. Grok\'s command scan is **flat and non-recursive**, so subdirectory namespacing is not supported: a nested `git/commit.md` is flattened onto `commit.md`, and two nested commands with the same basename collide (rulesync warns and the last one wins). And Grok collects skills before commands, letting **skills win name collisions** — a `.grok/skills//` shadows `.grok/commands/.md`, so avoid giving a rulesync skill and a rulesync command the same name when targeting Grok. Any extra frontmatter keys are preserved on round-trip under the `grokcli:` block. See the [skills, plugins and marketplaces docs](https://docs.x.ai/build/features/skills-plugins-marketplaces).\n\n> **Rovo Dev CLI note:** Rovo Dev\'s "saved prompts" are a file-based custom-command surface made of a `prompts.yml` manifest plus per-prompt Markdown content files, invoked via `/prompts [title] [extra]`. Rulesync writes the content (no frontmatter) to `.rovodev/prompts/.md` (project) / `~/.rovodev/prompts/.md` (global, via `--global`), and rebuilds the sibling `.rovodev/prompts.yml` / `~/.rovodev/prompts.yml` manifest with one `{ name, description, content_file }` entry per prompt, `content_file` pointing at `prompts/.md` (resolved relative to `prompts.yml`, matching Rovo Dev\'s own resolution order). The `prompts` array is fully replaced from the current rulesync commands on each generate (mirrors the Rovodev MCP adapter fully replacing `mcpServers`); any other top-level key in an existing manifest is preserved, and the manifest is never deleted. See the [saved prompts](https://support.atlassian.com/rovo/docs/save-and-reuse-a-prompt-in-rovo-dev-cli/) and [CLI commands](https://support.atlassian.com/rovo/docs/rovo-dev-cli-commands/) docs.\n\n## `rulesync/subagents/*.md`\n\nExample:\n\n```md\n---\nname: planner # subagent name\ntargets: ["*"] # * = all, or specific tools\ndescription: >- # subagent description\n This is the general-purpose planner. The user asks the agent to plan to\n suggest a specification, implement a new feature, refactor the codebase, or\n fix a bug. This agent can be called by the user explicitly only.\nclaudecode: # for claudecode-specific parameters\n model: inherit # opus, sonnet, haiku, fable, a full model id, or inherit (default)\n tools: ["Read", "Write"] # (optional) allowed tools (string or list)\n disallowedTools: ["Bash"] # (optional) tools to remove (string or list)\n permissionMode: default # (optional) default | acceptEdits | bypassPermissions | plan\n maxTurns: 20 # (optional) maximum agentic turns\n skills: ["skill-creator"] # (optional) Agent Skills to utilize (string or list)\n color: cyan # (optional) UI color (e.g. red, blue, green, cyan, ...)\n memory: project # (optional) user | project | local\n effort: high # (optional) low | medium | high | xhigh | max\n isolation: worktree # (optional) run the subagent in an isolated git worktree\n background: false # (optional) run the subagent in the background\n initialPrompt: "Start by reading the spec." # (optional) seed prompt for the subagent\n mcpServers: {} # (optional) MCP server config (passed through verbatim)\n hooks: {} # (optional) hook config (passed through verbatim)\ncopilot: # for GitHub Copilot specific parameters\n tools:\n # Listed tools are emitted verbatim; omit `tools` entirely to grant the agent\n # all tools. `agent/runSubagent` is opt-in — add it explicitly only when this\n # subagent needs to orchestrate other subagents.\n - web/fetch\n - agent/runSubagent\nopencode: # for OpenCode-specific parameters\n mode: subagent # (optional, defaults to "subagent") OpenCode agent mode\n model: anthropic/claude-sonnet-4-20250514\n temperature: 0.1\n tools:\n write: false\n edit: false\n bash: false\n permission:\n bash:\n "git diff": allow\nkilo: # for Kilo-specific parameters\n mode: all # (optional, defaults to "all") use "subagent" for hidden/subagent-only agents\ncursor: # for Cursor-specific parameters (generated to .cursor/agents/*.md)\n model: inherit # (optional, defaults to "inherit") model id, or "inherit" to use the parent\'s model\n readonly: false # (optional, defaults to false) restrict the subagent to read-only tools\n is_background: false # (optional, defaults to false) run the subagent as a background agent\njunie: # for JetBrains Junie CLI specific parameters (generated to .junie/agents/*.md; also imported from .agents/*.md)\n tools: ["Read", "Grep", "Edit"] # allowed tools\n disallowedTools: ["Bash", "WebSearch"] # disallowed tools\n mcpServers: ["github"] # MCP servers the subagent may use\n model: sonnet # model id\n reasoningLevel: high # low | medium | high\n maxTurns: 20 # max agentic turns\n skills: ["kotlin", "writerside"] # Agent Skills to utilize\n allowPromptArgument: true # whether the subagent accepts a prompt argument\ntakt: # takt specific parameters (optional; emitted under .takt/facets/personas/)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\nroo: # for Roo Code specific parameters (optional; aggregated into the root .roomodes file)\n slug: planner # (optional) custom mode slug (^[a-zA-Z0-9-]+$); defaults to the sanitized file name\n whenToUse: "When planning a task" # (optional) guidance for automated mode selection\n customInstructions: "Be concise." # (optional) extra behavioral guidelines\n roleDefinition: "You are the planner." # (optional) overrides the body as the mode\'s roleDefinition\n groups: # (optional, defaults to ["read", "edit", "command", "mcp"]) tool access\n - read\n - ["edit", { fileRegex: "\\\\.md$", description: "Markdown files" }]\n---\n\nYou are the planner for any tasks.\n\nBased on the user\'s instruction, create a plan while analyzing the related files. Then, report the plan in detail. You can output files to @tmp/ if needed.\n\nAttention, again, you are just the planner, so though you can read any files and run any commands for analysis, please don\'t write any code.\n```\n\n> **Antigravity note:** Antigravity custom agents (CLI v1.1.6+, shared by the IDE and the CLI) are emitted as Markdown + YAML frontmatter to `.agents/agents/.md` (project) and `~/.gemini/config/agents/.md` (global, via `--global`); the body after the frontmatter is the agent\'s system prompt. Both `antigravity-ide` and `antigravity-cli` read the same two locations, so enabling both writes the same file — the same way they already share `.agents/hooks.json`. Antigravity also accepts a directory form (`/agent.md`); Rulesync emits and imports the flat file form only. `name` and `description` are **required** upstream, so a canonical subagent without a description gets a minimal generated fallback rather than a file Antigravity refuses to load. Because the two share that file, every Antigravity target reads the `antigravity-ide` and `antigravity-cli` blocks merged in a fixed order (the CLI block wins) — the same rule the MCP feature uses for the same shared-output reason — so generation order never changes the file\'s content; the `antigravity-plugin` block is layered on top for the plugin bundle only. Besides the shared `name`/`description`, those blocks accept these optional fields (all preserved on round-trip): `tools` (string list), `mainAgent` (boolean, default `true`), `subagent` (boolean, default `true`), `model` (`inherit` | `flash` | `pro`), `commandExecutionPolicy` (`off` | `auto` | `eager` | `sandbox`), `mcpServers`, `skills`, and `plugins`. `hidden` and `inheritMcp` appear in the v1.1.6 release notes but not in the documented frontmatter table, so they pass through verbatim with no behavior modeled around them; the schema is loose, so any extra keys survive the round-trip too. The `antigravity-plugin` target writes the same file format into a plugin bundle\'s `agents/` directory (project scope only). See the [Antigravity subagents docs](https://antigravity.google/docs/subagents) and the [plugin bundle layout](https://antigravity.google/docs/cli/plugins).\n\n> **Qwen Code note:** Subagents are emitted as Markdown + YAML frontmatter under `.qwen/agents/` (project) and `~/.qwen/agents/` (user/global, via `--global`); the body is the subagent\'s system prompt. Besides the shared `name`/`description`, the `qwencode:` block accepts these optional fields (all preserved on round-trip): `model`, `approvalMode` (`default` | `plan` | `auto-edit` | `yolo` | `bubble`), `tools` (allowlist), `disallowedTools` (denylist), `maxTurns`, `color`, `mcpServers` (per-agent MCP overrides — accepts both a record of server specs, matching Qwen\'s documented shape, and a plain array of server names), and `hooks` (per-agent hook registrations). See the [Qwen Code sub-agents docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/sub-agents.md).\n\n> **Kimi Code note:** Subagents are emitted as Markdown files under `.kimi-code/agents/` (project) and `~/.kimi-code/agents/` (global). The shared `name` and required `description` fields are written to YAML frontmatter; Kimi-specific `whenToUse`, `override`, `tools`, `disallowedTools`, and `subagents` fields can be authored under the `kimi-code:` block and round-trip unchanged. Kimi recursively scans both its Kimi-specific agents directory and the shared `.agents/agents/` directory, so Rulesync imports nested Markdown files from both locations and flattens them into `.rulesync/subagents/.md` using the validated kebab-case agent name. The Kimi-specific root has precedence over `.agents/agents/`; if multiple source files resolve to the same logical agent name, the first one wins and Rulesync warns about the duplicate. The shared root is import-only and is never removed by Kimi-target orphan deletion. See the [Kimi Code custom-agents docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html).\n\n> **Kiro CLI note:** Subagents are emitted as JSON agent configurations under `.kiro/agents/` (project) and `~/.kiro/agents/` (global). Kiro allows the JSON `name` field to be omitted, in which case the filename stem is the agent name; Rulesync accepts that form on import and writes the derived name into the Rulesync frontmatter. Imports through the `kiro-cli` target retain `targets: ["kiro-cli"]`, so they can be generated back to the same target without changing the target metadata.\n\n> **Cline note:** Cline file-based agents are emitted as YAML files (`.yaml`) into `.cline/agents/` (project) and `~/.cline/agents/` (global, via `--global`). The file is a YAML frontmatter block followed by the system prompt body, matching Cline\'s agent config loader: `name` and `description` are **required** (Cline cli-v3.0.23+ refuses to load an agent whose `description` is missing or empty — a canonical subagent without one gets a minimal generated fallback rather than a file Cline cannot load), and the typed optional fields `tools`, `skills`, `providerId`, `modelId`, and `maxIterations` round-trip through the `cline:` section. Import reads `.yml` alongside `.yaml`, matching Cline\'s `isYamlFile()`.\n\n> **Devin note:** Devin Local custom subagent profiles are emitted as `AGENT.md` files in a **directory-per-agent** layout: `.devin/agents//AGENT.md` (project) and `~/.config/devin/agents//AGENT.md` (global, via `--global`). The directory name `` is the profile id (derived from the rulesync subagent file name). The `AGENT.md` is a YAML frontmatter block followed by the subagent\'s system prompt. Besides the shared `name`/`description`, the `devin` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, override the subagent LLM), `allowed-tools` (list of strings, restrict available tools), `permissions` (object with `allow`/`deny`/`ask` string lists, override tool permissions), and `max-nesting` (integer, enable nested subagent spawning up to the given depth). See the [Devin subagents docs](https://docs.devin.ai/cli/subagents).\n\n> **Reasonix note:** Reasonix native subagents are Skill profiles emitted as `SKILL.md` files in a **directory-per-agent** layout: `.reasonix/skills//SKILL.md` (project) and `~/.reasonix/skills//SKILL.md` (global, via `--global`). The directory name `` is the profile id (derived from the rulesync subagent file name). A subagent is a Skill whose YAML frontmatter declares `invocation: manual` and `runAs: subagent` — Rulesync always injects both markers so the SKILL.md is recognized as a manually invoked subagent rather than an auto-discovered skill. Besides the shared `name`/`description`, the `reasonix` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, subagent LLM), `effort` (string, reasoning effort), `allowed-tools` (list of strings, restrict available tools), and `color` (string, display color). The schema is loose, so any extra keys survive the round-trip. See the [Reasonix subagent profiles docs](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SUBAGENT_PROFILES.md).\n\n> **Roo skills/commands note (final v3.54.0 state — Roo Code is EOL and its repository archived):** Commands are generated to `.roo/commands/` (project) and `~/.roo/commands/` (global, via `--global`; project wins on a name collision). Skill frontmatter beyond `name`/`description` — most usefully `modeSlugs: string[]` for mode targeting — is authored via the `roo:` section of `.rulesync/skills/*/SKILL.md` and lifted back into it on import, so it survives the round-trip. A localRoot rule is emitted as `AGENTS.local.md`, the personal, gitignored override file Roo loads alongside `AGENTS.md`.\n\n> **Zoo Code note:** Zoo Code ([Zoo-Code-Org/Zoo-Code](https://github.com/Zoo-Code-Org/Zoo-Code)) is the community continuation of the archived Roo Code, named by the Roo shutdown notice and continuing Roo\'s release numbering (v3.54.0 → v3.72.0 as of 2026-07-25). It still resolves `~/.roo` and the project `.roo/` layout — the `.zoo` renaming is confined to provider/auth code — so the `zoocode` target reuses the `roo` adapters\' path model verbatim across rules (including `AGENTS.local.md` local-root handling), ignore (`.rooignore`), MCP (`.roo/mcp.json`), commands (`.roo/commands/`), skills (`.roo/skills/`, `roo:` frontmatter section), and subagents (the aggregated `.roomodes` file). Shared mode/skill fields keep riding the `roo:` frontmatter sections, so one rulesync source never produces two spellings; targeting both `roo` and `zoocode` writes the same files, so pick one target per project — and note the fail-open hazard the shared `.roomodes` creates: a `--targets roo` generate rewrites it **without** `allowedMcpServers`, so opening that workspace in Zoo Code makes every MCP server available to the mode. The post-fork divergence is carried by the `zoocode:` subagent section: `allowedMcpServers` (Zoo Code v3.60.0+), a per-mode MCP server allowlist ("when omitted, all servers are available; when set, only the listed servers are injected"), emitted into the mode and lifted back into `zoocode:` on import. See the [Zoo Code docs](https://docs.zoocode.dev/features/custom-modes).\n\n> **Roo note (as of 2026-06-16):** Roo Code reads project custom modes from a single aggregated `.roomodes` file at the workspace root (YAML; JSON also accepted). Rulesync therefore collapses every Roo-targeted subagent into that file\'s `customModes` array — each subagent becomes one mode whose `slug` is derived from the file name (sanitized to `^[a-zA-Z0-9-]+$`), `name`/`description` come from the shared frontmatter, and `roleDefinition` is the subagent body. The optional `roo:` block supplies `groups` (defaults to `["read", "edit", "command", "mcp"]`), `whenToUse`, `customInstructions`, an explicit `slug`, and a `roleDefinition` override. (Roo\'s previous `.roo/subagents/` output was inert — Roo Code never read it.) See the [Roo custom-modes docs](https://roocodeinc.github.io/Roo-Code/features/custom-modes).\n\n> **OpenCode import note:** OpenCode lets agents live both as Markdown files under `.opencode/agents/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `agent` key. On import, rulesync reads both: each inline entry\'s `prompt` becomes the subagent body (a `"{file:./path}"` reference is resolved relative to the config file\'s location, as OpenCode does), and the remaining fields (`description`/`mode`/`model`/`tools`/`permission`/...) become frontmatter under the `opencode:` block. A Markdown file takes precedence over an inline entry with the same name.\n\n> **Kilo note (as of 2026-05-13):** Kilo\'s documented default for user-defined agents is `mode: all`, which makes the agent available both as a top-level pick and as a subagent. Set `kilo.mode: subagent` to opt into hidden/subagent-only behavior.\n\nBesides `mode`, the `kilo` subagent block accepts these optional fields (all preserved on round-trip):\n\n| Field | Type | Notes |\n| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `displayName` | string | Human-friendly name shown in pickers |\n| `model` | string | Model id |\n| `variant` | string | Model variant |\n| `temperature` | number | Sampling temperature |\n| `top_p` | number | Nucleus-sampling parameter |\n| `permission` | string \\| object | Permission profile name, or a per-tool `{ : { allow, deny, ask } }` object |\n| `prompt` | string | Inline system prompt |\n| `color` | string | UI color |\n| `native` | boolean | Native (built-in) agent flag |\n| `hidden` | boolean | Hide from top-level picker |\n| `disable` | boolean | Disable the agent |\n| `deprecated` | boolean | Mark as deprecated |\n| `steps` | positive integer | Maximum agentic iterations before a text-only response is forced (an explicit `null` is accepted and round-trips as-is, so a file that already carries one still imports; earlier Rulesync versions took a list of step objects here, which Kilo never accepted) |\n| `options` | object | Free-form key/value options |\n\n> **Migration note (`steps`):** earlier Rulesync versions typed `steps` as a list of step objects, which Kilo never accepted — a subagent authored that way produced a file Kilo ignored. It is now the iteration count Kilo documents, so a `kilo` block (or a `.kilo/agents/*.md` file) still carrying the list form fails validation with the offending file named, and the run stops rather than writing a file that would not work. Replace the list with the number of iterations you want, or drop the field.\n\n> **Hermes Agent note:** Project generation writes subagent JSON specs under `.hermes/rulesync/subagents/` and installs `.hermes/plugins/rulesync-subagents/`. The plugin resolves specs relative to its own installation, so the same code works in project and global scope. For project scope, Rulesync also enables `rulesync-subagents` in `$HERMES_HOME/config.yaml`. Run Hermes from the trusted project root with `HERMES_ENABLE_PROJECT_PLUGINS=true`; Rulesync deliberately does not persist that global trust gate.\n\n## `.rulesync/checks/*.md`\n\nCode review checks are per-check instructions an agent runs during code review. Each check is a single Markdown file with YAML frontmatter (the source of the check identity is the file name — e.g. `.rulesync/checks/security.md` defines the `security` check).\n\nExample:\n\n```md\n---\ntargets: ["*"] # * = all, or specific tools\ndescription: Flags common security issues # (optional) short summary of the check\nseverity: high # (optional) low | medium | high | critical\ntools: ["Read", "Grep"] # (optional) tool names the check may use\n---\n\nReview the diff for injection vulnerabilities, hardcoded secrets, and unsafe\ndeserialization. Report each finding with a file and line reference.\n```\n\nAmp, Cursor, Hermes Agent, Rovo Dev CLI and Takt consume checks. Amp receives one Markdown file per check:\n\n- **Project scope:** `.agents/checks/.md`\n- **Global scope** (`--global`): `~/.config/amp/checks/.md`\n\nFor Cursor, checks are [Bugbot](https://cursor.com/docs/bugbot) code review instructions, and Bugbot reads one aggregated instruction file per directory rather than a file per check — so every check targeting Cursor collapses into the repository-root `.cursor/BUGBOT.md`. Each check becomes one section: an HTML-comment marker carrying the check name, an `## ` heading, and the check body as the instruction text (the `description` is used when the body is empty). Bugbot reads the file as free prose, so a check\'s `severity` and `tools` have no equivalent there — they are not written and do not come back on import, and neither is `description` whenever the check also has a body. Project scope only: Bugbot reads repository files and there is no user-level instruction file. Because Bugbot only sees the file when it is **committed**, the derived `.gitignore` deliberately does not ignore `.cursor/BUGBOT.md` (Rovo Dev\'s `.rovodev/.review-agent.md` gets the same treatment) — commit the generated file for the reviewer to pick it up. Example output:\n\n```md\n\n\n## security\n\nReview the diff for injection vulnerabilities.\n```\n\nOn import the markers split the file back into one check per section, each with `targets: ["*"]` because Bugbot instructions are plain prose that applies anywhere. Content sitting ahead of the first marker — and a hand-written `BUGBOT.md` with no markers at all — is imported as a single `bugbot` check, so nothing in the file is dropped. A check body that contains a marker line of its own (a quoted rulesync doc fragment, say) is written as `` and restored on import, so it cannot split the check it belongs to. Bugbot also merges nested `/.cursor/BUGBOT.md` files found while traversing upward from changed files, but rulesync check sources carry no directory-placement semantics, so only the root file is generated.\n\nGenerating checks for Cursor replaces `.cursor/BUGBOT.md`, so run `rulesync import --targets cursor --features checks` first if the repository already has a hand-written one — generation warns when it is about to replace instructions rulesync did not write. Deletion is guarded: a `BUGBOT.md` holding anything rulesync did not write — no marker at all, or hand-written text ahead of the first marker — is never removed, so dropping the last check that targets Cursor takes rulesync\'s own output with it and nothing else.\n\nFor Rovo Dev CLI, checks are [code-review custom instructions](https://support.atlassian.com/rovo/docs/set-custom-instructions-for-code-reviews/), and Rovo Dev reads one plain-Markdown file rather than a file per check — so every check targeting Rovo Dev collapses into `.rovodev/.review-agent.md` (note the leading dot in the file name). The file takes **no frontmatter**. Everything else works exactly as it does for Cursor Bugbot above, because the two surfaces are the same shape: one marked-up section per check, `severity`/`tools` dropped, `description` used only when the body is empty, markers splitting the file back on import (with a hand-written file importing as a single `review-agent` check), the same `` escaping, the same replace-and-warn on generate, and the same deletion guard for a file holding anything rulesync did not write. Project scope only — these are per-repository review instructions and Rovo Dev documents no user-level equivalent, which is the opposite of the Rovo Dev permissions surface (global only).\n\nFor Hermes Agent, Rulesync writes project-local JSON specs under `.hermes/plugins/rulesync-checks/checks/` and a `rulesync-checks` plugin beside them. Its one-shot [`pre_verify` hook](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-verify) fires only for coding turns with changed paths and `attempt == 0`, then asks Hermes to run all configured checks before finishing. `tools` is preserved as advisory guidance because Hermes does not enforce an Amp-style per-check tool allowlist. Run Hermes with the project plugin explicitly trusted for that invocation:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-checks` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged, preserving Hermes\'s global trust boundary. Existing plugin configuration is preserved; an explicit `plugins.disabled` conflict fails generation.\n\nFor Takt, checks are **quality gates**, and they live in the `workflow_overrides` block of the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global) rather than in files of their own — so every check targeting Takt collapses into that one file. A check becomes one gate: by default a **string gate**, the body text, which Takt injects into the agent step prompt as a completion directive (the `description` is used when the body is empty, and the file stem when neither is set); with `command` in the check\'s `takt` frontmatter block, a **command gate** (`{type: command, name, command, cwd, timeout_ms}`), which Takt runs after the step and fails on a non-zero exit code. `name` defaults to the file stem so Takt\'s logs identify the gate. `name`, `cwd` and `timeout_ms` belong to a command gate, so they are ignored on a check that states no `command`. `steps` and `personas` in that block scope a gate to named workflow steps or personas (`workflow_overrides.steps..quality_gates`); an unscoped gate applies everywhere, and a gate naming both is written to both. `quality_gates_edit_only` is a property of the block as a whole, so one check setting it turns it on for all of them. It reaches only the unscoped gates — Takt runs a `steps`/`personas`-scoped gate whether or not the step may edit files — so the reach it narrows is the other checks\' unscoped gates, which is warned about when there are any. Takt gates carry no severity or tool allowlist, so a check\'s `severity` and `tools` are not written and do not come back on import. Takt merges quality gates additively and dedupes them (project over global over the workflow YAML\'s own gates). Example:\n\n```md\n---\ntargets: ["takt"]\ntakt:\n command: ./.takt/quality-gates/check.sh # omit for a string gate\n timeout_ms: 300000\n steps: ["review"] # (optional) scope to named workflow steps\n personas: ["coder"] # (optional) scope to named personas\n---\n```\n\nA command gate\'s `command` is run by Takt with no further gating — Takt\'s default-deny `workflow_command_gates.custom_scripts` policy applies to gates declared in workflow YAML, not to these — so read the frontmatter of any check you obtain with `rulesync fetch` before generating. The body of a check that carries a `command` is not used. `workflow_overrides` is owned by the checks feature: it is rewritten from `.rulesync/checks/` on every generate, so a gate deleted there disappears from `config.yaml` too, while every other key of the file is preserved and the file is never deleted. When checks remain but none of them target Takt — every one names other tools — the block is retracted with a warning, whether an earlier generate or a hand edit put it there; that is what owning the key means, so author gates as checks rather than in `config.yaml`. A project with no `config.yaml` does not get one. Emptying `.rulesync/checks/` altogether is different: the feature has no source to generate from, so nothing runs and the gates already in `config.yaml` stay. Delete the block by hand in that case — a command gate left behind keeps running after every step. On import, each gate becomes its own check file, named from the gate text or the command gate\'s `name`. A string gate is prose that applies anywhere, so it imports with `targets: ["*"]` like an Amp check; a command gate imports as `targets: ["takt"]`, since its body is empty and would generate an empty check for every other tool. A gate scoped to both a step and a persona becomes two checks, and a command gate carrying a field of the wrong type is left in `config.yaml` rather than imported. The default-deny `workflow_command_gates.custom_scripts` policy is **not** written here — Takt validates it against gates declared in workflow YAML, not against these, and it is authorable through the `takt` block of `.rulesync/permissions.*`, which owns the security policies. See the [Takt workflows docs](https://github.com/nrslib/takt/blob/main/docs/workflows.md).\n\nThe emitted Amp frontmatter is derived from the source as follows:\n\n| Amp field | Source |\n| ------------------ | -------------------------------------------------------- |\n| `name` | the source file basename without `.md` (required by Amp) |\n| `description` | `description` |\n| `severity-default` | `severity` |\n| `tools` | `tools` |\n\nThe frontmatter schema is loose, so extra Amp-specific keys survive a generate/import round-trip (except keys that collide with a rulesync tool-target name such as `cursor` — those are treated as tool-scoped sections and are not re-emitted). A tool-scoped section (e.g. `amp: { "severity-default": "critical" }`) overrides the canonical values for that tool — the tool-specific value takes precedence, and the section itself is not emitted (except `name`, which always comes from the file name). On import, `severity-default` maps back to the generic `severity` field, and the `name` field is dropped because it is re-derived from the file name on the next generate.\n\n> **v1 limitation:** Amp also discovers subtree-scoped checks (e.g. `api/.agents/checks/`), but rulesync sources carry no directory-placement semantics, so those subtree-scoped checks are not generated. See the [Amp manual](https://ampcode.com/manual).\n\n## `.rulesync/skills/*/SKILL.md`\n\nExample:\n\n```md\n---\nname: example-skill # skill name\ndescription: >- # skill description\n A sample skill that demonstrates the skill format\ntargets: ["*"] # * = all, or specific tools\n# (optional) shared default for tools that support the flag — claudecode, cursor,\n# zed, pi, qwencode, grokcli, and factorydroid. Any of those tool sections can\n# override it by setting their own `disable-model-invocation` value below.\ndisable-model-invocation: true\n# (optional) shared default for tools that support the flag — claudecode, qwencode,\n# vibe, grokcli, and factorydroid. Any of those tool sections can override it by\n# setting their own `user-invocable` value below.\nuser-invocable: false\nclaudecode: # for claudecode-specific parameters\n model: sonnet # opus, sonnet, haiku, or any string\n when_to_use: When the user asks to review a PR # (optional) extra trigger context appended to description\n allowed-tools: # (optional) tools usable without asking; accepts a string or a list\n - "Bash"\n - "Read"\n - "Write"\n - "Grep"\n disallowed-tools: # (optional) removes these tools while the skill is active (string or list)\n - "WebFetch"\n effort: high # (optional) effort while active: low | medium | high | xhigh | max\n argument-hint: "[pr-number]" # (optional) autocomplete hint for expected arguments\n arguments: # (optional) named positional arguments for $name substitution (string or list)\n - "pr_number"\n context: fork # (optional) set to "fork" to run the skill in a forked subagent context\n agent: code-reviewer # (optional) subagent type to use when context: fork\n background: false # (optional, context: fork only) wait for the forked subagent in the invoking turn instead of backgrounding it (default true)\n shell: bash # (optional) shell for ! command blocks: bash (default) or powershell\n hooks: # (optional) hooks scoped to the skill\'s lifecycle (free-form per the Claude Code docs)\n PreToolUse:\n - matcher: "Bash"\n disable-model-invocation: true # (optional) disable model invocation for this skill\n user-invocable: false # (optional) hide from the / menu while keeping model access\n scheduled-task: true # (optional) emit to .claude/scheduled-tasks//SKILL.md instead of .claude/skills//SKILL.md\n # paths (optional) limits auto-activation to matching globs. Accepts a\n # comma-separated string, e.g. paths: "src/**/*.ts,test/**/*.ts", or a list:\n paths:\n - "src/**/*.ts"\n - "test/**/*.ts"\ncodexcli: # for codexcli-specific parameters\n short-description: A brief user-facing description\n # The following sections are emitted to the agents/openai.yaml sidecar next to SKILL.md.\n # See https://developers.openai.com/codex/skills.md\n interface: # (optional) UI metadata\n display_name: Example Skill\n short_description: A brief user-facing description\n default_prompt: Do the thing\n policy: # (optional) invocation policy\n allow_implicit_invocation: false # only invoke explicitly via $skill\n dependencies: # (optional) tool dependencies\n tools:\n - type: mcp\n value: example\n description: Example MCP tool\npi: # for Pi Coding Agent-specific parameters (optional; Agent Skills standard)\n # Authored either as a canonical list or as the spec\'s space-delimited string;\n # emitted to SKILL.md as the string, and imported back as the list.\n allowed-tools:\n - "Bash"\n - "Read"\n disable-model-invocation: true # (optional) disable model invocation for this skill\n license: MIT # (optional)\n compatibility: "Requires git and jq" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n metadata: # (optional) free-form metadata\n author: rulesync\nreplit: # for Replit Agent-specific parameters (optional; Agent Skills standard)\n # Authored either as a canonical list or as the spec\'s space-separated string;\n # emitted to SKILL.md as the string, and imported back as the list.\n allowed-tools:\n - "Bash"\n - "Read"\n license: MIT # (optional)\n compatibility: "Requires git and docker" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n metadata: # (optional) free-form metadata\n author: rulesync\ndeepagents: # for deepagents-cli (dcode)-specific parameters (optional; Agent Skills standard)\n # Authored as a canonical list; emitted to SKILL.md as a space-delimited string\n # (e.g. "Bash Read") because dcode rejects a YAML list at runtime.\n allowed-tools:\n - "Bash"\n - "Read"\n license: MIT # (optional)\n compatibility: # (optional) free-form compatibility metadata\n deepagents-version: ">=0.1.0"\n metadata: # (optional) free-form metadata\n author: rulesync\nopencode: # for OpenCode-specific parameters (optional)\n license: MIT # (optional)\n compatibility: # (optional) free-form compatibility metadata\n opencode-version: ">=1.16.0"\n metadata: # (optional) free-form metadata\n author: rulesync\n allowed-tools: # (optional) Anthropic-spec passthrough; OpenCode ignores unknown fields\n - "Bash"\n - "Read"\nkilo: # for Kilo Code-specific parameters (optional)\n license: MIT # (optional)\n compatibility: # (optional) free-form compatibility metadata\n kilo-version: ">=7.0.0"\n metadata: # (optional) free-form metadata\n author: rulesync\n allowed-tools: # (optional) backward-compat passthrough; not part of Kilo\'s official SKILL.md frontmatter\n - "Bash"\n - "Read"\nkimi-code: # for Kimi Code-specific parameters (optional; project/global .kimi-code/skills/)\n type: inline # (optional) prompt, inline, or flow\n whenToUse: "When reviewing pull requests" # (optional) model invocation hint\n disableModelInvocation: false # (optional) prevent automatic model invocation\n arguments: ["pull_request"] # (optional) named arguments, also accepts a whitespace-separated string\nagentsskills: # for the Agent Skills standard target (optional; supports project + global ~/.agents/skills/)\n license: MIT # (optional)\n compatibility: "Requires Python 3.14+ and uv" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n metadata: # (optional) free-form metadata (spec-recommended place for skill versioning)\n version: "1.0.0"\n allowed-tools: "shell" # (optional, experimental) space-separated string or list\ncopilot: # for GitHub Copilot-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n license: MIT # (optional)\n allowed-tools: "shell" # (optional) tools pre-approved without per-use confirmation\ncopilotcli: # for GitHub Copilot CLI-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n license: MIT # (optional)\n allowed-tools: "shell" # (optional) tools pre-approved without per-use confirmation\n argument-hint: "[message]" # (optional) hint shown for the skill\'s expected arguments\n user-invocable: true # (optional, default true) whether users can run it with /SKILL-NAME\n disable-model-invocation: false # (optional, default false) stop the agent from invoking it on its own\nrovodev: # for Rovo Dev CLI-specific parameters (optional; Agent Skills standard)\n allowed-tools: "grep bash" # (optional) space-separated string (a YAML list is also accepted)\n license: MIT # (optional)\n compatibility: "Requires Python 3.14+ and uv" # (optional) free-form string (object form also accepted)\n metadata: # (optional) free-form metadata\n author: rulesync\nzed: # for Zed-specific parameters (optional)\n disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\ncursor: # for Cursor-specific parameters (optional)\n paths: # (optional) glob patterns (string or list) scoping the skill to matching files\n - "src/**/*.ts"\n disable-model-invocation: true # (optional) only include the skill when invoked via /skill-name\n metadata: # (optional) free-form metadata\n author: rulesync\nfactorydroid: # for Factory Droid-specific parameters (optional)\n disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\n user-invocable: false # (optional) hide from the slash-command menu, keep model access\ntakt: # takt specific parameters (optional; emitted under .takt/facets/knowledge/ — frontmatter is dropped on emit)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\n extends: "base" # (optional) emit a leading `{extends:}` facet-inheritance directive (Takt 0.39.0+)\ndevin: # for Devin-specific parameters (optional; project .devin/skills/, global ~/.config/devin/skills/)\n argument-hint: "[environment]" # (optional) hint shown after the slash-command name\n model: "fast" # (optional) model override while the skill runs\n subagent: true # (optional) run the skill in a subagent (string or boolean per Devin\'s docs)\n agent: "deployer" # (optional) named agent profile to run the skill with\n allowed-tools: # (optional) tools available while the skill runs (string or list)\n - "Bash(git status:*)"\n permissions: {} # (optional) auto-approval rules applied while the skill runs (load-bearing since Devin CLI v3000.1.23)\n triggers: ["user"] # (optional) invocation gating; omitted = user + model. The shared disable-model-invocation / user-invocable flags map onto this when unset.\nqwencode: # for Qwen Code-specific parameters (optional; project .qwen/skills/, global ~/.qwen/skills/)\n priority: 10 # (optional) higher values appear earlier in /skills listings\n paths: # (optional) glob patterns gating model discovery to matching files (a scalar is coerced to the array Qwen Code requires)\n - "src/**/*.ts"\n user-invocable: false # (optional) hide from slash-command invocation, keep model access\n disable-model-invocation: true # (optional) hide from the model but allow direct user invocation\n allowedTools: # (optional) permissions.allow-syntax rules auto-approved while the skill is active\n - "Shell(git status:*)"\n model: "fast" # (optional) model override while the skill runs (model id, fast, authType:modelId, inherit)\n hooks: {} # (optional) session-scoped hooks registered while the skill runs (settings.json shape)\n when_to_use: "Use when deploying" # (optional) invocation guidance surfaced in the SkillTool description\n argument-hint: "[environment]" # (optional) hint shown after the slash-command name in completion\ngrokcli: # for Grok CLI-specific parameters (optional)\n user-invocable: false # (optional) hide from the skill tool, keep model access\n disable-model-invocation: true # (optional) block auto-invocation, keep the slash command\nvibe: # for Vibe Code-specific parameters (optional)\n user-invocable: false # (optional) hide from slash-command invocation, keep model access\n allowed-tools: "Bash Read" # (optional) space-delimited or list of allowed tool names\n---\n\nThis is the skill body content.\n\nYou can provide instructions, context, or any information that helps the AI agent understand and execute this skill effectively.\n\nThe skill can include:\n\n- Step-by-step instructions\n- Code examples\n- Best practices\n- Any relevant context\n\nSkills are directory-based and can include additional files alongside SKILL.md.\n\nWhen `claudecode.scheduled-task: true` is set, that skill is emitted only as a Claude Code scheduled task and is not emitted to other tools even if `targets` contains `"*"`.\n```\n\n> **`.agents/skills/` ownership note:** `.agents/skills/` is not an AGENTS.md convention — the AGENTS.md standard defines only `AGENTS.md` itself. It is the [Agent Skills](https://agentskills.io/specification) project location, which the native `agentsskills` target writes. Several targets write there — `agentsskills`, `agentsmd`, `aiassistant`, `codexcli`, `amp`, `zed`, `replit` and both Antigravity targets — because they all implement the same convention. Each native target writes its own documented frontmatter, so enabling more than one and reordering `--targets` can change which optional keys end up in the file; that is inherent to several tools sharing one path and is not specific to any of them.\n\n> The **simulated** `agentsmd` writer is the exception that is fixed: it has no frontmatter model of its own (the AGENTS.md standard defines no skills at all), so it used to overwrite the native output with a bare `name`/`description` pair and silently drop `license`, `compatibility`, `metadata` and `allowed-tools`. It now emits exactly what `agentsskills` emits, so a simulated writer can never degrade the file a native target owns.\n\n> **Claude Code nested skills note:** Claude Code v2.1.178+ also loads skills from **nested** `.claude/skills/` directories below the working directory (a skill in `apps/web/.claude/skills/` becomes available when working on files there, and a name clash with a root skill keeps both under a directory-qualified name like `apps/web:deploy`). `rulesync import --targets claudecode --features skills` discovers those nested directories (import-only, lenient, same dependency/build-directory exclusions as the nested `AGENTS.md` scan; symlinks not followed) so an existing nested skill is no longer invisible. On a name clash the root skill wins the import — rulesync\'s flat skill namespace cannot express the qualified variant. Generation stays targeted at the project-root `.claude/skills/`; to scope a skill\'s _activation_ to a subtree, use the `paths` frontmatter, or run a separate generate with `--output-roots ` for physical co-location.\n\n> **Note:** `claudecode.disallowed-tools` (a space/comma-separated string or a YAML list) removes the listed tools from the model while the skill is active. The same field is available on Claude Code slash commands. Both round-trip through the `claudecode` frontmatter section.\n\n> **Note:** Codex CLI reads UI metadata, invocation policy, and tool dependencies from an `agents/openai.yaml` sidecar next to `SKILL.md` (Codex\'s `SKILL.md` frontmatter only carries `name` and `description`). When `codexcli.interface`, `codexcli.policy`, or `codexcli.dependencies` is present, Rulesync emits `.agents/skills//agents/openai.yaml` and reads it back on import. If the sidecar is emitted and `interface.short_description` is absent, the legacy `codexcli.short-description` is routed there. See the [Codex skills docs](https://developers.openai.com/codex/skills.md).\n\n> **Reasonix note:** Reasonix discovers Anthropic-style directory-layout skills (`/SKILL.md`) under `.reasonix/skills/` (project) / `~/.reasonix/skills/` (global, via `--global`). Rulesync emits the portable `name`/`description` frontmatter (Reasonix supports additional optional keys, but only that pair is modeled); the schema is loose, so any extra keys on an imported `SKILL.md` survive the round-trip. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md).\n\n> **Hermes Agent note:** Hermes skills are global-only under `~/.hermes/skills//SKILL.md`. Standard Agent Skills fields (`license`, `compatibility`, and `allowed-tools`) round-trip through `agentsskills` and are normalized to the Agent Skills spec shapes described above (so `allowed-tools` is written and imported the same way as for `agentsskills`); Hermes-native fields such as `version`, `author`, `platforms`, `environments`, `required_environment_variables`, `required_credential_files`, and `metadata.hermes` round-trip through `hermesagent`. Canonical `name` and `description` always own those two frontmatter keys.\n\n> **Kimi Code note:** Kimi Code discovers skills under `.kimi-code/skills/` (project) and `~/.kimi-code/skills/` (global), plus the shared `.agents/skills/` root at either scope. Rulesync generates the recommended directory layout (`/SKILL.md`) and imports both that layout and flat `.md` skills; for flat files, a missing `name` comes from the filename and a missing `description` falls back to the first non-empty body line (up to 240 characters), matching Kimi. Imported skills are written to `.rulesync/skills//SKILL.md`, using the normalized logical frontmatter name rather than the source directory or filename. Duplicate precedence follows Kimi\'s case-insensitive logical frontmatter `name`: the Kimi-specific root takes precedence over `.agents/skills/`, and a directory skill takes precedence over a same-named flat file within one root. Shared roots are import-only and are never removed by Kimi-target orphan deletion. Besides `name`/`description`, Rulesync maps Kimi\'s `type`, `whenToUse`, `disableModelInvocation`, and `arguments` frontmatter through the `kimi-code:` block and preserves supporting files beside directory-layout `SKILL.md`. The shared top-level `disable-model-invocation` value supplies the Kimi flag unless the tool-specific block overrides it. See the [Kimi Code Agent Skills docs](https://moonshotai.github.io/kimi-code/en/customization/skills.html).\n\n## `.rulesync/mcp.jsonc`\n\n`.rulesync/mcp.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/mcp.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nExample:\n\n```json\n{\n "mcpServers": {\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json",\n "serena": {\n "description": "Code analysis and semantic search MCP server",\n "type": "stdio",\n "command": "uvx",\n "args": [\n "--from",\n "git+https://github.com/oraios/serena",\n "serena",\n "start-mcp-server",\n "--context",\n "ide-assistant",\n "--enable-web-dashboard",\n "false",\n "--project",\n "."\n ],\n "env": {}\n },\n "context7": {\n "description": "Library documentation search server",\n "type": "stdio",\n "command": "npx",\n "args": ["-y", "@upstash/context7-mcp"],\n "env": {}\n }\n }\n}\n```\n\n### Tool-scoped server blocks (`{toolname}.mcpServers`)\n\nServers under the shared `mcpServers` key are emitted to every targeted tool. To scope a server to a single tool, add a tool-scoped `{toolname}` block alongside it — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.permission` in `.rulesync/permissions.jsonc`:\n\n```jsonc\n{\n "mcpServers": {\n "shared-server": { "type": "stdio", "command": "echo" },\n },\n "claudecode": {\n "mcpServers": {\n // Added only to Claude Code\'s MCP config.\n "claude-only-server": { "type": "http", "url": "https://example.com/mcp" },\n // `null` removes a shared server for Claude Code only.\n "shared-server": null,\n },\n },\n}\n```\n\n- A tool-scoped entry with the same name as a shared server **replaces it wholesale** for that tool (no field-level merge).\n- A tool-scoped entry set to `null` **removes** the shared server for that tool.\n- Any MCP-capable `--targets` name is accepted as a block key (`claudecode`, `cursor`, `codexcli`, ...). Targets that share one output file resolve identically so the shared file never depends on generation order: the deprecated `claudecode-legacy` target reads the `claudecode` block; the `kiro-cli` / `kiro-ide` targets read the `kiro` block (all three write the same `.kiro/settings/mcp.json`); and the `antigravity-ide` / `antigravity-cli` targets both apply both `antigravity-*` blocks in a fixed order (`antigravity-ide` first, then `antigravity-cli` — the CLI block wins per server) because they share their output file at both scopes (`.agents/mcp_config.json` in project mode, `~/.gemini/config/mcp_config.json` in global mode).\n\n> **Generation filter: per-server `enabled`.** Set `"enabled": false` on a server (in the shared map or a tool-scoped block) to keep the definition in the source file while emitting it to **no** tool config at all — a temporary off switch that does not lose the entry. Omitted means enabled, so existing configs keep generating everything; writing `"enabled": true` is opt-in clarity. This is distinct from the canonical `disabled`, which is a **pass-through** field the tools read (written as `disabled: true`, or translated to each tool\'s own spelling): `enabled: false` wins and drops the server entirely, while `disabled` only matters for servers still emitted. The field is rulesync-source-only and never reaches generated output — several tools (OpenCode, Kilo, Grok CLI, Goose) have a native `enabled` field with different semantics — and import never invents it: a tool\'s native enabled/disabled state keeps mapping to the canonical `disabled` (though a stray hand-written `enabled` in a passthrough-imported tool file does come back as the canonical filter). Two edges to know: a tool-scoped entry **replaces the shared entry wholesale**, so a same-named tool-scoped entry without `enabled: false` re-emits the server for that tool (per-tool re-enabling); and on merge-style shared configs (e.g. Hermes Agent\'s `config.yaml`), disabling a previously generated server stops writing it but does not remove the already-written entry — same as deleting the definition.\n\n> **Deprecated: per-server `targets`.** The older per-server `"targets": ["tool", ...]` array is still honored as a filter (a missing value or `["*"]` means every tool), but it is deprecated and logs a warning at generate time. Migrate by moving the server into the matching `{toolname}.mcpServers` block(s).\n\n> **JetBrains AI Assistant note:** Rulesync writes the native `{ "mcpServers": { ... } }` configuration to `.ai/mcp/mcp.json` in project mode and `~/.ai/mcp/mcp.json` in global mode. Both scopes support STDIO and remote server entries using the shape documented in [JetBrains AI Assistant\'s MCP guide](https://www.jetbrains.com/help/ai-assistant/mcp.html).\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/mcp.jsonc`:\n\n```json\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json",\n "mcpServers": {}\n}\n```\n\n### Transport types (`type` / `transport`)\n\nThe `type` (and the equivalent `transport`) field accepts `local`, `stdio`, `sse`, `http`, `ws`, and `streamable-http`. `streamable-http` is the MCP specification\'s name for the HTTP transport and is accepted as an alias of `http`, so configurations copied from a server\'s documentation work unchanged. `ws` is the WebSocket transport (a persistent bidirectional connection) and accepts the same `url`/`headers`/`headersHelper`/`timeout` fields as `http`. Tools that do not recognize a given transport keep it on round-trip but may ignore it at runtime.\n\n> **OpenCode skills note:** on import, Rulesync also reads the `skills.paths` array of `opencode.json` / `opencode.jsonc` ("Additional paths to skill folders") and scans each entry as an extra skill root, so skills a project keeps outside `.opencode/skills/` are no longer invisible to `rulesync import`. These roots are import-only — generation keeps writing to Rulesync\'s own managed root — and a skill of the same name found in a managed root still wins. Each entry is resolved against the directory the config was read from — the project root in project mode, `~/.config/opencode/` in global mode — which is what OpenCode itself does. An absolute path, or one that escapes that directory, is ignored, and a directory under a configured root that is not a skill is skipped with a warning rather than failing the run, since a configured root is arbitrary user territory. `skills.urls` is a remote-fetch surface and is out of scope for a file-based generator.\n\n> **Kilo Code note:** Kilo\'s MCP config uses its own native shape in `kilo.jsonc` (`type: "local" | "remote"`, `environment`, `enabled`, `command` as an array). Rulesync maps `stdio`/`local` ⇄ Kilo `local` and `http`/`sse` ⇄ Kilo `remote`; on import, Kilo `remote` is normalized to the canonical `http` transport (the deprecated `sse` is no longer emitted). The Kilo-specific `timeout` (local + remote, a positive integer in milliseconds) and `oauth` (remote only — either an OAuth-config object or `false` to disable auto-detection) fields are preserved on round-trip. The `kilo.jsonc` `skills` config key (`skills.paths` for extra skill locations and `skills.urls` for remote skill manifests) is likewise preserved when Rulesync writes the file. A bare `{"enabled": false}` entry — Kilo\'s way of switching off a server another config layer defines, such as the global config or a marketplace — round-trips as itself: it imports as a canonical server carrying only `disabled: true`/`disabled: false` and no transport, and a server in that shape is written back as `{"enabled": …}` rather than as a local server with an empty command it cannot start. The enabled state has to be stated outright in both directions: for a transport-less server that says nothing about `disabled`, a toggle already in `kilo.jsonc` is left exactly as it is, and if there is none the server is skipped with a warning — a toggle overrides the layer that defines the server, so writing `enabled: true` for it would switch back on what you turned off there. Kilo\'s per-tool `enabledTools`/`disabledTools` reach the generated file at all now — they used to be stripped before this adapter saw them, so a filter read out of `kilo.jsonc` was deleted from it on the next generate. A skipped server\'s filters are written to the `tools` map either way, since that map is keyed by server name and reaches servers `mcp` does not list; on import, a `tools` entry naming no listed server comes back as a server carrying nothing but the filters, so it survives the round-trip. A server with no transport — a toggle, or one of those filter-only entries — is imported into the tool-scoped `kilo.mcpServers` block rather than the shared `mcpServers` map, because an entry with no command and no url is a server the other tools\' configs cannot start. All of this applies equally to OpenCode: its published schema carries the same bare-toggle union member, it round-trips a toggle as itself under the same explicit-state rule, its `tools` map works the same way, and its transport-less servers land in `opencode.mcpServers`. The entry must carry no field of a local or remote server (`type`, `command`, `url`, `headers`, `environment`, `cwd`, `timeout`, `oauth`); an entry that is malformed in some other way still fails loudly rather than being quietly read as a toggle and written back with its command, headers, or OAuth secrets gone, while an unrelated key Kilo adds later is accepted rather than failing the run (it is not carried across the round-trip, though — a toggle imports as its enabled state and nothing else). Since a toggle keeps nothing but its enabled state, a canonical server that declares no transport but still carries fields such as `args` or `env` is written as a toggle with those fields dropped and a warning naming them. A server that names a transport it cannot reach — a `type` with no `command`, an `http` with no `url` — is skipped with a warning instead, because `{"type": "local", "command": []}` is a server Kilo cannot start. An existing `kilo.jsonc` carrying that shape (earlier Rulesync versions wrote it) imports as a server with no transport rather than failing the run. The same applies to OpenCode, whose config uses the same shape. Rejecting it used to fail the whole `--targets kilo` run rather than the MCP feature alone, because `kilo.jsonc` is the file the rules feature writes too.\n\n> **Zed note:** Zed configures MCP servers under `context_servers` in its shared settings file (`.zed/settings.json` project, `~/.config/zed/settings.json` global — `%APPDATA%\\Zed\\settings.json` on Windows), whose value is an untagged shape with no `type` field: a stdio server is `{"command": , "args", "env", "timeout"}`, a remote one `{"url", "headers", "timeout"}`, and an extension-provided one neither. Rulesync translates the canonical fields into those shapes instead of forwarding them verbatim (which used to hand Zed keys it silently ignores — most seriously `disabled: true`, which left the server **enabled**): `disabled: true` becomes `enabled: false` (and imports back as `disabled: true`), the `httpUrl` alias is normalized to `url`, an array `command` is flattened to Zed\'s single command string with the rest prepended to `args`, and canonical-only fields (`type`/`transport`, `alwaysAllow`, `trust`, `cwd`, `networkTimeout`, the Kiro lists) are dropped. Fields rulesync does not model — a remote server\'s `oauth` block, an extension server\'s `settings` — pass through untouched, so they are best authored in the tool-scoped `zed.mcpServers` block. A server Zed cannot start is skipped with a warning rather than written broken: an `sse` or `ws` server (Zed has neither transport), a remote server with no `url`, a local one with no `command`. A server with no transport at all is written as Zed\'s extension-provided variant, and on import such an entry lands in the tool-scoped `zed.mcpServers` block rather than the shared `mcpServers` map, since other tools cannot start it.\n\n> **Kimi Code note:** MCP servers are written to `.kimi-code/mcp.json` (project) and `~/.kimi-code/mcp.json` (global). Kimi Code supports stdio, HTTP, and SSE plus `env`, `cwd`, `headers`, `bearerTokenEnvVar`, `enabled`, `startupTimeoutMs`, `toolTimeoutMs`, `enabledTools`, and `disabledTools`; Rulesync preserves the canonical fields that Kimi accepts. Canonical `local` maps to stdio and `streamable-http` maps to HTTP. WebSocket servers are skipped with a warning because Kimi has no WebSocket transport. A `kimi-code` block may also carry `startupTimeoutMs` / `toolTimeoutMs`, which are **not** per-server: they become Kimi\'s `[mcp] startup_timeout_ms` / `tool_timeout_ms` defaults in the shared global `~/.kimi-code/config.toml`, applying to every MCP server including ones Rulesync did not write (a per-server value in `mcp.json` still wins). Global scope only, since `config.toml` has no project counterpart, and merged in place so the `hooks` and `permission` sections of the same file survive. The merge is per key: authoring only one of the two timeouts leaves a hand-written sibling alone, and dropping the override entirely leaves the section as it stands rather than deleting it — remove the keys from `config.toml` by hand if you want them gone. See the [Kimi Code MCP docs](https://moonshotai.github.io/kimi-code/en/customization/mcp.html) and [config-files reference](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html#mcp).\n\n> **Hermes Agent note:** Hermes MCP servers live under `mcp_servers` in the shared `~/.hermes/config.yaml`. Rulesync preserves OAuth fields (`redirect_uri`, `redirect_host`, `redirect_port`, `client_id`, `client_secret`, and `scopes`) plus `idle_timeout_seconds`, `max_lifetime_seconds`, `ssl_verify` (`true`/`false` or a PEM CA-bundle path), `skip_preflight`, and the `sampling` mapping (carried as an opaque object so new sub-keys keep working). On import, portable server fields remain in shared `mcpServers`; Hermes-only fields are isolated in the full `hermesagent.mcpServers.` replacement block so they cannot leak to other targets.\n\n> **Devin note:** Since Devin v3000.3 (the Local 3.6 release), MCP servers live in a dedicated `mcpServers`-keyed file: `.devin/mcp_config.json` (project) and `~/.config/devin/mcp_config.json` (global, via `--global`). The file is MCP-only and rulesync-owned (rewritten whole, deletable), unlike the shared `.devin/config.json` that permissions and hooks keep patching in place. Rulesync no longer writes the legacy `config.json` `mcpServers` key — Devin auto-migrates it away on startup, so re-seeding it would fight the migration — but import still falls back to that key when no `mcp_config.json` exists, so pre-v3000.3 repos migrate cleanly. The gitignored personal override `.devin/mcp_config.local.json` is never read or written (it is covered by the derived `.gitignore`). See the [Devin MCP configuration docs](https://docs.devin.ai/cli/extensibility/mcp/configuration).\n\n> **Warp note:** Warp reads file-based MCP servers from `.warp/.mcp.json` (project) and `~/.warp/.mcp.json` (global). Warp spells the working directory `working_directory` (used for resolving relative paths), so the canonical `cwd` is translated to it on generate and back on import; a tool-native `working_directory` already on the server wins over `cwd`. See the [Warp MCP docs](https://docs.warp.dev/agent-platform/capabilities/mcp/).\n\n> **Takt note (partial / transport-allowlist only):** Takt does **not** have a project- or global-level registry of MCP server _definitions_. The concrete `mcp_servers` map (`command`/`args`/`env` or `type`/`url`/`headers`) is declared **per workflow step** inside individual workflow YAML files; there is no top-level `mcp_servers` key in `config.yaml`, and Takt\'s config loader hard-rejects unknown top-level keys (introduced with MCP support in [Takt v0.21.0](https://github.com/nrslib/takt/blob/main/CHANGELOG.md)). What `config.yaml` _does_ hold is the **default-deny transport allowlist** `workflow_mcp_servers: { stdio, sse, http }` — without it, workflow-defined MCP servers are refused regardless of how they are declared. So Rulesync emits **only** this allowlist into the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global), enabling exactly the transports your `.rulesync/mcp.jsonc` servers use (`local`/`stdio` ⇒ `stdio`; `sse` ⇒ `sse`; `http`/`streamable-http`/`ws` ⇒ `http`). The merge is in place — every other top-level key (`provider`, `provider_profiles`, …) is preserved and the file is never deleted. **Documented lossiness:** per-server names, commands, env, URLs, and headers are not representable in `config.yaml` and are intentionally **not** written; you still declare the concrete servers in your workflow YAML steps, and Rulesync only opens the transport gate that permits them. As a corollary, **import** cannot reconstruct server definitions from a transport allowlist and yields an empty `mcpServers` map. See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\n### MCP Tool Config (`enabledTools` / `disabledTools`)\n\nYou can control which individual tools from an MCP server are enabled or disabled using `enabledTools` and `disabledTools` arrays per server.\n\n```json\n{\n "mcpServers": {\n "serena": {\n "type": "stdio",\n "command": "uvx",\n "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"],\n "enabledTools": ["search_symbols", "find_references"],\n "disabledTools": ["rename_symbol"]\n }\n }\n}\n```\n\n- `enabledTools`: An array of tool names that should be explicitly enabled for this server.\n- `disabledTools`: An array of tool names that should be explicitly disabled for this server.\n\n> **Kiro note:** Kiro MCP servers are written under `mcpServers` in `.kiro/settings/mcp.json` (project) and `~/.kiro/settings/mcp.json` (global). Kiro supports `disabledTools` natively and Rulesync preserves it on generate and import. Kiro does not expose a corresponding per-server `enabledTools` allowlist, so that field is omitted for Kiro targets.\n\n> **Qwen Code note:** MCP servers are written to the `mcpServers` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global, via `--global`). Qwen supports stdio (`command`/`args`), SSE (`url`), and HTTP (`httpUrl`) transports. Rulesync maps the canonical per-server `enabledTools` ⇄ Qwen\'s `includeTools` (allowlist) and `disabledTools` ⇄ Qwen\'s `excludeTools` (denylist). Other top-level keys in `settings.json` are preserved on round-trip.\n\n> **Codex CLI server-name note:** Codex requires MCP server names matching `[a-zA-Z0-9_-]+`, so Rulesync auto-normalizes non-conforming names on generate (lowercase, runs of other characters become `_`, leading/trailing `_` trimmed) — e.g. `Postgres MCP - Production - Read Only` becomes `postgres_mcp_production_read_only`. If two names normalize to the same Codex name, the last processed server overwrites the earlier one (with a warning). A name with no representable characters at all (e.g. a fully Japanese name) falls back to a stable hash-derived name like `mcp_1a2b3c4d` instead of being dropped; rename the server in `.rulesync/mcp.jsonc` to pick a readable Codex name. This normalization is one-way: importing back from the generated `config.toml` yields the normalized name, not the original.\n\n### Codex-specific: pass shell env vars to MCP servers (`envVars`)\n\nCodex CLI supports a per-server array of shell env var names to inherit when launching the MCP server process. The source schema uses `envVars` (camelCase, matching the project convention used by sibling fields like `enabledTools`/`disabledTools`); the codex generator renames it to `env_vars` (snake_case) for codex\'s native `config.toml` format.\n\nThis is distinct from `env` (which is a literal `{name: value}` map) — `envVars` is a list of names whose **values come from the user\'s environment at runtime**. Both fields may coexist on the same server.\n\n```json\n{\n "mcpServers": {\n "pal": {\n "type": "stdio",\n "command": "uvx",\n "args": [\n "--from",\n "git+https://github.com/BeehiveInnovations/pal-mcp-server.git",\n "pal-mcp-server"\n ],\n "envVars": ["OPENAI_API_KEY", "OPENROUTER_API_KEY", "GEMINI_API_KEY"]\n }\n }\n}\n```\n\nGenerated `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.pal]\ntype = "stdio"\ncommand = "uvx"\nargs = ["--from", "git+https://github.com/BeehiveInnovations/pal-mcp-server.git", "pal-mcp-server"]\nenv_vars = ["OPENAI_API_KEY", "OPENROUTER_API_KEY", "GEMINI_API_KEY"]\n```\n\nAn entry may also be an object naming the environment to read the variable from: `{ "name": "REMOTE_TOKEN", "source": "remote" }` reads it from the remote executor environment (and requires remote MCP stdio support), while a bare name and `"source": "local"` read from Codex\'s own environment. The object form is written to `config.toml` as an inline table, matching Codex\'s documented shape. Only `name` and `source` are accepted in that object — Codex rejects an unknown key there, and rejecting one server\'s entry would take the whole `config.toml` down with it, so Rulesync fails on the canonical file instead. For the same reason an entry that a `config.toml` already holds in some other shape is dropped with a warning on import rather than written into a `.rulesync/mcp.jsonc` the next generate would refuse.\n\n- Emitted only into the codex CLI output. Stripped from `RulesyncMcp.getMcpServers()` so it does not appear in other tools\' generated configs (Claude Code, Kilo, OpenCode, Gemini CLI, Cursor, Cline, Junie, Factorydroid, Rovodev, etc.).\n- Use this for secrets and API keys you do not want literal-encoded into a committed `mcp.json`.\n- Precedence: codex CLI resolves these names from the user\'s runtime shell environment. If a name is also set in `env` (literal value), the codex CLI behavior is upstream-defined; see the [Codex configuration reference](https://developers.openai.com/codex/config-reference#mcp_serversid-env_vars) (last checked 2026-05-13) for the exact resolution rule.\n\n### Codex-specific: run a stdio server remotely (`experimentalEnvironment`)\n\nFor stdio servers, `experimentalEnvironment: "remote"` starts the server through a remote executor environment when one is available. It is written as `experimental_environment` in `config.toml`. Like `envVars`, it is stripped before every other tool\'s MCP config is written, so it cannot leak into a config that would not understand it — and for the same reason, a server config copied straight out of a `config.toml` may spell it `experimental_environment`, which is accepted and normalized on the way to Codex.\n\nSee the [Codex MCP reference](https://learn.chatgpt.com/docs/extend/mcp) for both fields.\n\n#### Codex-specific: OAuth client id (`oauth.clientId` → `client_id`)\n\nA server\'s `oauth` block is preserved in the canonical Claude Code shape (camelCase `clientId`), but Codex CLI reads the OAuth client id from snake_case `oauth.client_id`. Without it, `codex mcp login ` falls back to dynamic client registration and fails for providers that do not support it (e.g. Slack). The codex generator therefore **duplicates** `clientId` into a sibling `client_id`, keeping the camelCase key so tools that expect it keep working:\n\n```toml\n[mcp_servers.slack.oauth]\nclientId = "1601185624273.8899143856786"\nclient_id = "1601185624273.8899143856786"\ncallbackPort = 3118\n```\n\nOnly a string `clientId` is duplicated (a non-string value would not be a usable OAuth client id), and an explicit `client_id` already present in the source is left untouched. On import, `client_id` collapses back to the canonical `clientId` (and is dropped when both are present) so the round-trip stays stable.\n\n> **Grok CLI note:** MCP servers are written to a `[mcp_servers.]` table in `.grok/config.toml` (project) / `~/.grok/config.toml` (global, via `--global`). The file is treated as shared Grok config: Rulesync only replaces the `mcp_servers` key and preserves every other table on round-trip, and it is never deleted. Unlike Codex CLI, Grok uses a literal `env` table (it does not support the `env_vars` runtime-passthrough list) and has no per-server tool allow/deny lists, so the only field rename is `disabled` (rulesync) ⇄ `enabled = false` (grok); an active server simply omits `enabled`. Servers with no environment variables are emitted without a dangling `[mcp_servers..env]` table (empty nested tables are stripped), and a server whose entire configuration would be empty is dropped with a warning.\n\n### Goose-specific: MCP servers as `extensions` (global) and open-plugin manifest (project)\n\nGoose configures MCP servers in two locations depending on scope:\n\n- **Global (`--global`):** MCP servers are written as **extensions** in the shared user config `~/.config/goose/config.yaml`. The schema is non-standard, so Rulesync maps canonical MCP fields to Goose\'s: `command` → `cmd` (an array `command` folds its tail into `args`), `env` → `envs`, `url`/`httpUrl` → `uri`, and `disabled: true` → `enabled: false`. The `type` is derived — `command` ⇒ `stdio`, a remote `url` ⇒ `streamable_http` (or `sse` when the canonical `type` is `sse`). Each extension also carries its own `name`. Generation merges the `extensions:` block into the existing `config.yaml`, preserving other Goose settings (model, provider, ...), and the file is never deleted. This location supports **both stdio and remote** (http/sse) servers.\n- **Project:** Goose v1.39.0+ discovers MCP extensions in **open plugins** at `/.agents/plugins//.mcp.json` (and `~/.agents/plugins//.mcp.json` at user scope). Rulesync emits `.agents/plugins/rulesync/.mcp.json`, reusing the same `.agents/plugins/rulesync/` tree already used for Goose hooks. The manifest uses the **Claude-style** `{ "mcpServers": { "": { "command", "args", "env", "cwd" } } }` shape. This manifest is **stdio-only** — it cannot express `url`/`headers`, so **remote (http/sse) servers are skipped with a warning** in project mode; sync them with `--global` to `~/.config/goose/config.yaml` instead. The `.mcp.json` manifest is owned by Rulesync and is deleted when no servers remain.\n\nSee the [Goose extensions docs](https://block.github.io/goose/docs/getting-started/using-extensions/) and [open-plugins MCP PR #9471](https://github.com/block/goose/pull/9471).\n\n### Goose-specific: commands as recipes, subagents as custom agents\n\nGoose [recipes](https://block.github.io/goose/docs/guides/recipes/recipe-reference/) are reusable YAML workflow files. **Commands** map to top-level recipes at `.goose/recipes/.yaml` (project) and `~/.config/goose/recipes/.yaml` (global); the command body becomes the recipe `prompt`, `title` defaults to the file name and `description` to the rulesync `description` (falling back to `title`), `version` defaults to `1.0.0`, and any other recipe field round-trips through the rulesync `goose` section of a command.\n\n**Subagents** map to Goose\'s [custom agents](https://block.github.io/goose/docs/guides/context-engineering/custom-agents/) (v1.34.0+): Markdown files with `name` (required) / `description` / `model` frontmatter whose body is the agent instructions, invocable via `@name` or delegation. They are emitted to the goose-specific discovery dirs `.goose/agents/.md` (project) and `~/.config/goose/agents/.md` (global), so the output cannot collide with a future shared `.agents/agents/` target; `model` and unknown future fields round-trip through the rulesync `goose` subagent section. Earlier rulesync versions emitted subagents as sub-recipe YAML under `.goose/recipes/subagents/` — a location Goose\'s agent discovery never scans, so those files were inert; they are no longer generated (stale outputs stay gitignored but are not cleaned up automatically).\n\n### Vibe-specific: stdio `cwd` and MCP `[auth]` block\n\nVibe (mistral-vibe) MCP servers live in `[[mcp_servers]]` arrays of the shared `.vibe/config.toml`. In addition to the flat fields, Rulesync passes through the stdio `cwd` (working directory), a structured per-server `auth` block (Vibe v2.15.0+), and the four keys Vibe\'s `/mcp` panel writes back when you toggle a server or one of its tools — `prompt`, `sampling_enabled`, `disabled` and `disabled_tools`. Because `mcp_servers` is replaced as a whole array on each generate, a server Rulesync writes is seeded from the on-disk entry of the same name for exactly those keys, so a toggle you made in the TUI survives — unless your `.rulesync/mcp.json` states the value itself, which wins. `disabled_tools` is the canonical `disabledTools` under Vibe\'s spelling; `prompt` and `sampling_enabled` have no canonical equivalent and pass through as-is. The `auth` table is discriminated on `type`: `static` (`headers`, `api_key_env`, `api_key_header`, `api_key_format`) and `oauth` (`scopes`, `client_id` / `client_metadata_url`, `redirect_port`). Because Vibe rejects mixing legacy top-level static-auth keys with an explicit `[auth]` block, Rulesync suppresses the legacy keys (`headers`/`api_key_env`/`api_key_header`/`api_key_format`) whenever a server carries an `auth` block. Servers added outside Rulesync — through `vibe mcp add` (v2.23.0) or the `/mcp add` panel, both of which persist straight into this TOML — are preserved after the managed entries instead of being deleted by the array replace. The flip side: removing a server from `.rulesync/mcp.jsonc` no longer removes it from `config.toml`; delete it there too (or run `vibe mcp remove`). See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/config/models.py`).\n\n> **GitHub Copilot (VS Code) MCP note:** the `copilot` target writes `.vscode/mcp.json`, which has three documented top-level sections: `servers`, `inputs` (secret prompts referenced as `${input:id}`) and `sandbox` (filesystem/network rules for sandboxed servers, added in VS Code v1.112). Rulesync owns and replaces only `servers`; the rest of the document — including any future top-level section — is read back and preserved on each generate. VS Code recommends committing this file, so dropping an `inputs` entry would leave `${input:…}` unresolvable and the affected servers would fail to start. If the existing file cannot be parsed, generate fails with an error rather than overwriting it. See the [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).\n\n> **Rovo Dev CLI MCP note:** Rovo Dev documents the per-server transport key as `transport` (`stdio` | `http` | `sse`), not the canonical `type`. Rulesync translates on the way out (`local` → `stdio`, `streamable-http` → `http`) and back on import; `ws` has no Rovo Dev equivalent, so those servers are skipped with a warning, and a `transport` value outside Rovo Dev\'s vocabulary is dropped on import rather than written into the canonical config, whose transport field is a strict enum. `disabled` is stripped from the servers that are written, since `mcp.json` is not where a Rovo Dev server is switched on and off — see the toggle handling below. `mcp.json` is written at both scopes: the global `~/.rovodev/mcp.json`, and in project mode the repo-committed `.rovodev/mcp.json` the Bitbucket Cloud Agentic Pipelines guide documents (pointed at via `mcp.mcpConfigPath`; not gitignored, since committing it is the point). A server the canonical config marks `disabled: true` is no longer dropped: its definition is written to `mcp.json` (minus the flag, which the file cannot express) and its name goes to `mcp.disabledMcpServers` in the sibling `config.yml` — the key Rovo Dev actually consults — where rulesync owns the toggle for the servers it manages while user keys (`mcpConfigPath`, `allowedMcpServers`, ...) and disabled names for unmanaged servers survive. On import, names listed in `mcp.disabledMcpServers` come back as `disabled: true` on the matching servers; a `config.yml` that exists but cannot be parsed fails both directions closed (the import errors instead of silently re-enabling servers, and generate skips disabled definitions it cannot switch off). Since the project `mcp.json` is committed, prefer env-var references over literal credentials in server `env`/`headers`; note that rulesync owns the `mcpServers` map in that file, so servers hand-added there (rather than to `.rulesync/mcp.jsonc`) are replaced on the next generate. See the [Rovo Dev MCP docs](https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/).\n\n> **Reasonix note:** MCP servers are written as `[[plugins]]` array-of-tables entries (Reasonix\'s MCP-compatible external plugins) in `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`). Each entry carries a `name` plus the standard transport fields: `type` selects the transport (`stdio` default — `command`/`args`/`env`; `http`, a.k.a. `streamable-http` — `url`/`headers`; `sse`, the legacy 2024-11-05 HTTP+SSE transport, written verbatim — Reasonix re-implemented it in v1.17.18, and collapsing it onto `http` pointed the client at Streamable HTTP so the server could not connect). The file is treated as shared Reasonix config: Rulesync only replaces the `plugins` key and preserves every other table (providers, ui, agent, …) on round-trip, and it is never deleted. Reasonix has no per-server tool allow/deny lists. The `trusted_read_only_tools` array (raw MCP tool names pre-seeded as trusted for planner/read-only use) is neither written nor imported: v1.17.18 retired it along with `default_tools_approval_mode`, `tools..approval_mode` and `approvals_reviewer` — installing a server is the authorization decision now, and Reasonix ignores the key on load and strips it the next time it saves that entry. Importing it would put a Reasonix-only dead key into the canonical `mcpServers` that every MCP target writes out, so it would surface in `.mcp.json` and the rest. Note that Rulesync owns the `plugins` key, so the next generate drops the key from an older `reasonix.toml` as well; nothing is lost that Reasonix still reads. An MCP server whose transport Reasonix does not implement (`ws`, including a `ws://`/`wss://` URL that states no transport at all) is skipped with a warning rather than written as a `type` its loader rejects. Each entry also supports `call_timeout_seconds` (a per-server MCP call timeout) and `tool_timeout_seconds` (a per-tool inline table keyed by raw MCP tool name). None of these have a deep canonical mapping, so they round-trip as passthrough fields on the canonical MCP server object. See the [Reasonix plugins guide](https://github.com/esengine/deepseek-reasonix/blob/main-v2/docs/GUIDE.md#plugins-mcp) and [SPEC.md](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md) (`[[plugins]]` schema).\n\n## `.rulesync/.aiignore` or `.rulesyncignore` (deprecated)\n\n> **Deprecation notice:** The `ignore` feature is deprecated in favor of the more expressive [`permissions` feature](#rulesync-permissions-jsonc). Existing ignore configurations, generation, import, conversion, and explicit `rulesync add ignore` scaffolding remain supported throughout Rulesync 14.x. Removal, if any, will be decided separately and will not occur before a future major release. `rulesync init` no longer enables or scaffolds ignore for new projects.\n\nRulesync continues to support a single legacy ignore list in either location:\n\n- `.rulesync/.aiignore` (preferred legacy location)\n- `.rulesyncignore` (older project-root location)\n\nRules and behavior:\n\n- You may use either location.\n- When both exist, Rulesync prefers `.rulesync/.aiignore` over `.rulesyncignore` when reading.\n- Explicitly running `rulesync add ignore` creates `.rulesync/.aiignore` when neither location exists.\n\nExample:\n\n```ignore\ntmp/\ncredentials/\n```\n\n### Migrating to permissions\n\nMove each ignore pattern into the `read` category of `.rulesync/permissions.jsonc` with the `deny` action:\n\n```jsonc\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json",\n "permission": {\n "read": {\n "tmp/**": "deny",\n "credentials/**": "deny",\n },\n },\n}\n```\n\nThis is the closest replacement for preventing an agent from reading ignored paths. If the old policy was also intended to prevent changes, repeat the patterns under `edit` and `write`. Target tools differ in the permission categories they can represent, so review the [Supported Tools and Features](./supported-tools.md) table and the tool-specific permission notes below before removing the old ignore feature from a multi-tool project.\n\n### Where ignore patterns are written per tool\n\nMost tools get a dedicated ignore file (for example `.cursorignore`,\n`.geminiignore`, `.clineignore`). Antigravity CLI is built on the same engine\nas Gemini CLI, so it reads the project-root `.geminiignore` file. Claude Code is the exception: it does not\nread a separate ignore file, so Rulesync writes the deny list into Claude\nCode\'s settings file as `permissions.deny` entries (`Read()`).\n\nReasonix has no ignore file either, so its deny list goes into the `[permissions]` table of the shared `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`) as `Read()` entries — the same Claude-Code-style rule syntax the permissions feature writes there. `deny` is used rather than `[sandbox].forbid_read` because deny rules take glob specifiers and are documented as "a hard block in every mode", while `forbid_read` takes absolute paths with no documented glob support. The file is shared with the MCP and permissions features: only `Read(...)` deny entries are replaced, every other table and deny entry is preserved, and the file is never deleted. When the permissions feature also manages the `Read` category its explicit rules win, and the overwrite is warned about. As with the MCP and permissions features, the file is re-serialized on write, so hand-written comments, blank lines, and key ordering in `reasonix.toml` are not preserved.\n\nKiro reads `.kiroignore` in project scope and `~/.kiro/settings/kiroignore` in user scope. The `kiro`, `kiro-cli`, and `kiro-ide` targets therefore support `--global` for the deprecated ignore feature, as do `reasonix` and `zed` (whose config files exist in both scopes); the remaining ignore targets are project-only.\n\nZed has no ignore file: its deny list is the `private_files` array inside the shared settings file — `.zed/settings.json` in project scope and `~/.config/zed/settings.json` in global scope (`%APPDATA%\\Zed\\settings.json` on Windows). `private_files` is a worktree setting, and Zed layers default → user → project, so the key is honored in the user settings file too. The array is **owned wholesale by Rulesync**: it is replaced with the patterns from `.rulesync/.aiignore` on every generation, so a pattern deleted there is retracted from `settings.json` instead of surviving forever. When no patterns remain at all, the key is removed rather than written as `[]` — Zed ships a populated default `private_files` (`**/.env*`, `**/*.pem`, …) that any user or project value replaces wholesale, so an empty array would switch its secret redaction off. Every other key in the file — including the MCP `context_servers` and permissions `agent` blocks and unrelated editor settings — is preserved, and the file is never deleted.\n\nGoose retired `.gooseignore` upstream ("removed some time ago in favour of other ignore things like gitignore etc" — [goose#10343](https://github.com/aaif-goose/goose/issues/10343)), so rulesync no longer generates it; the replacement guidance is `.gitignore` plus tool permissions. Stale `.gooseignore` files from earlier versions stay gitignored but are not cleaned up automatically.\n\nCline\'s `.clineignore` is still emitted, but its own docs now title it "deprecate soon" and state it is not a security or access-control boundary — upstream\'s replacement direction is a Cline plugin enforcing via a `beforeTool` hook. Treat the matrix ✅ as a deprecated surface.\n\nHermes Agent uses a project-local `rulesync-ignore` plugin under `.hermes/plugins/`. It applies the canonical gitignore-style patterns through [`pre_tool_call`](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-tool-call) to `read_file`, `write_file`, and `patch` before execution, and filters ignored paths from `search_files` results through `transform_tool_result`. This is defense in depth around Hermes file tools; terminal commands and paths already present in conversation context are outside the plugin\'s enforcement surface. Hermes deliberately requires [explicit trust for project plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/), so run it from the trusted project root with that invocation opted in:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-ignore` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged. Existing configuration is preserved, explicit `plugins.disabled` conflicts fail, and `--delete` retains the additive user-level activation.\n\nFor Cursor, Rulesync emits only `.cursorignore` — the file that **blocks access\nentirely** (semantic search, Tab, Agent, Inline Edit, and `@`-mentions). Cursor\nalso supports a second file, `.cursorindexingignore`, which excludes files from\n**indexing only** while keeping them accessible to the AI on demand. These two\nfiles mean _different_ things, and Rulesync\'s `ignore` feature models a single\ncanonical ignore list per tool with no per-pattern distinction between\n"block access" and "exclude from indexing only". Emitting the same patterns to\nboth files would be incorrect, so `.cursorindexingignore` is intentionally **not\ngenerated** (an intentional non-goal). Author it by hand if you need\nindexing-only excludes.\n\nBy default, Claude Code\'s deny list is written to the **shared**\n`.claude/settings.json` so that the policy can be committed and reviewed by\nthe team. This is intentional (see issue #1094), but it means that running\n`rulesync gitignore` will not add `.claude/settings.json` to `.gitignore` —\nthat file may also contain other shared Claude config you actively want to\ncommit.\n\nIf you would rather keep the deny list out of version control, opt into the\n**local** mode using the per-feature options object form:\n\n```jsonc\n// rulesync.jsonc\n{\n "targets": ["claudecode"],\n "features": {\n "claudecode": {\n "ignore": { "fileMode": "local" },\n },\n },\n}\n```\n\n| `fileMode` | Output file | Tracked by git by default |\n| -------------------- | ----------------------------- | ----------------------------------------------------- |\n| `"shared"` (default) | `.claude/settings.json` | Yes — meant to be committed and shared with the team. |\n| `"local"` | `.claude/settings.local.json` | No — `rulesync gitignore` already excludes this file. |\n\n## `.rulesync/permissions.jsonc`\n\n`.rulesync/permissions.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/permissions.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nFor Hermes Agent imports, Rulesync treats a valid private `permissions.rulesync` block as provenance, then reconciles it with current native settings. `command_allowlist`, `approvals.deny`, and an enabled `security.website_blocklist` are authoritative for their mapped canonical rules, so hand edits replace stale generated values. A config with no private block still imports those native rules. Unmodeled `approvals`, `security`, `skills`, and `memory` settings remain under the `hermes` override; unrelated root settings such as `model` are not imported.\n\n`rulesync init` scaffolds a `codexcli` block with `approval_policy: "on-request"`, `approvals_reviewer: "auto_review"`, and `base_permission_profile: ":danger-full-access"`. On generation, the profile value becomes Codex\'s top-level `default_permissions`.\n\nPermissions define which tool actions are allowed, require confirmation, or are denied. The canonical format uses **lowercase tool category names** and **glob patterns** mapped to permission actions.\n\n**Permission actions:**\n\n- `allow` -- Automatically permitted without user confirmation\n- `ask` -- Requires user confirmation before execution\n- `deny` -- Blocked from execution\n\n**Supported tool categories:** `bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, and MCP-specific tool names (e.g., `mcp__puppeteer__puppeteer_navigate`)\n\nExample:\n\n```json\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json",\n "permission": {\n "bash": {\n "git *": "allow",\n "npm run *": "allow",\n "rm -rf *": "deny",\n "*": "ask"\n },\n "edit": {\n "src/**": "allow"\n },\n "read": {\n ".env": "deny",\n "credentials/**": "deny"\n }\n }\n}\n```\n\n### Tool-scoped permission blocks (`{toolname}.permission`)\n\nThe shared `permission` block applies to every targeted tool. To scope rules to a single tool, add a tool-scoped `{toolname}` block with a `permission` record of the same shape — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.mcpServers` in `.rulesync/mcp.jsonc`:\n\n```jsonc\n{\n "permission": {\n "bash": { "git *": "allow", "*": "ask" },\n },\n "claudecode": {\n "permission": {\n // Replaces the shared `bash` category for Claude Code only.\n "bash": { "git *": "allow", "git push *": "deny", "*": "ask" },\n },\n },\n}\n```\n\n- Categories are merged **per category**: a tool-scoped category replaces the shared category wholesale for that tool; shared categories it does not name still apply.\n- Any permissions-capable `--targets` name is accepted as a block key. `kiro-cli`/`kiro-ide` alias to the `kiro` key and `hermesagent` to `hermes` (matching the shared output file each writes).\n- OpenCode, Kilo, and Vibe keep their existing tool-native `permission` override semantics (bare action strings / tool-only categories / `sensitive_patterns` — see the tool-specific callouts below); their blocks are consumed by their translators instead of the central merge.\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/permissions.jsonc`:\n\n```json\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json",\n "permission": {}\n}\n```\n\nFor Claude Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.claude/settings.json` (project mode) or `~/.claude/settings.json` (global mode) using PascalCase tool names (e.g., `Bash(git *)`, `Edit(src/**)`, `Read(.env)`).\n\nClaude Code\'s file permission checks match only `Edit(path)` and `Read(path)` rules: a `Write(path)`, `NotebookEdit(path)` or `Glob(path)` rule "is accepted but never matched by those checks, so Claude Code warns at startup for each allow, deny, or ask rule in one of these unmatched forms" ([permissions docs](https://code.claude.com/docs/en/permissions), v2.1.210+). Rulesync therefore writes a canonical `write` or `notebookedit` rule that carries a pattern as `Edit(pattern)`, and a `glob` rule as `Read(pattern)`. A rule whose pattern is `*` is a tool-name rule with no path — it matches the tool everywhere and produces no warning — so it is still written as the bare `Write` / `NotebookEdit` / `Glob`. Entries an earlier Rulesync wrote in the warned form are replaced on the next generate, and so is a rewritten entry whose action changed, so flipping a rule from deny to allow never leaves the old deny behind to win. Rewriting a rule does **not** make Rulesync claim the `Edit` or `Read` namespace as a whole: a `Read(...)` deny the [ignore feature](#rulesyncignore) wrote, or an `Edit(...)` rule you added to `settings.json` by hand, is left alone unless the canonical config manages that category itself. Import stays tolerant of both forms, so an existing `settings.json` still round-trips; a rewritten rule comes back under `edit` or `read` rather than the category it was authored in, since that is the rule Claude Code actually applies. Note that this widens a `glob` **allow** rule: `Read(pattern)` permits reading the files\' contents, not just listing their names — the docs prescribe the substitution, but author `glob` allow rules with that in mind. When two categories resolve to the same entry with different actions (`edit` allowing what `write` denies, say) both are written and Rulesync warns — Claude Code applies deny first, then ask, then allow.\n\n> **Claude Code-only override (`claudecode` key):** Claude Code\'s `permissions` object also carries non-list fields with no canonical permission category — notably `defaultMode` (the session-start permission mode: `default` | `acceptEdits` | `plan` | `bypassPermissions`) and `additionalDirectories` (extra working directories). Add a tool-scoped `claudecode` override key alongside the shared block to author them: the fields under `claudecode.permissions` are merged into the settings `permissions` object and emitted **only** for Claude Code, while the shared `permission` block continues to drive the managed `allow`/`ask`/`deny` arrays. The block is a verbatim passthrough (so other/future `permissions` fields such as the org locks `disableBypassPermissionsMode`/`disableAutoMode` can be set too), but any `allow`/`ask`/`deny` placed inside it is ignored — rulesync owns those arrays. On import, the non-list `permissions` fields round-trip back into the `claudecode` override. Note that these fields are merged **additively** into the existing `settings.json` (so hand-added settings survive): removing a field from the `claudecode` override does not delete a value already written to `settings.json` — clear it there by hand.\n>\n> ```json\n> {\n> "permission": { "bash": { "git *": "allow" } },\n> "claudecode": {\n> "permissions": { "defaultMode": "acceptEdits", "additionalDirectories": ["../shared"] },\n> "sandbox": { "network": { "allowedDomains": ["example.com"], "strictAllowlist": true } }\n> }\n> }\n> ```\n>\n> The same override key also carries `sandbox`, the sibling top-level settings subtree governing the sandbox commands run in (`sandbox.network.*`, `sandbox.filesystem.*`, `sandbox.credentials`, `sandbox.allowAppleEvents`, ...). It has no canonical permission category either — it constrains _how_ a permitted command runs rather than which commands are permitted — so it is a verbatim passthrough on the same terms, merged into the top level of `settings.json` and round-tripped back on import. The merge is recursive, unlike the flat `permissions` fields above: `sandbox` subtrees carry restriction lists (`network.deniedDomains`, `filesystem.denyRead`), so setting one flag under `network` must not drop the denials beside it. A sibling key at any depth survives; a list you author replaces the existing list rather than being appended to. See the [sandboxing docs](https://code.claude.com/docs/en/sandboxing).\n\nFor OpenCode, this generates the `permission` object in `opencode.json` / `opencode.jsonc` (project mode) or `.config/opencode/opencode.json` / `.config/opencode/opencode.jsonc` (global mode), preserving other existing OpenCode config fields. OpenCode\'s `webfetch`, `websearch`, `todowrite`, `question`, and `doom_loop` keys accept only a single action string, so Rulesync emits their canonical `{ "*": "allow" }` form as `"allow"`. If one of these categories contains pattern-specific rules, Rulesync collapses them to the most restrictive action (`deny` > `ask` > `allow`) and logs a warning because OpenCode cannot represent those patterns; a map without `*` includes an implicit `ask` fallback so a narrow allowlist never becomes blanket `allow`, while an empty map becomes `deny` instead of falling through to OpenCode\'s default allow behavior.\n\n> **OpenCode-only override (`opencode` key):** OpenCode exposes permission categories that other tools do not understand (e.g. `external_directory`). Placing these in the shared `permission` block would push meaningless entries into Claude Code, Codex, etc. To scope them to OpenCode, add a tool-scoped `opencode` override key alongside the shared block — mirroring the tool-scoped override keys used by [hooks](#hooks) (`opencode.hooks`) and rules frontmatter. Categories under `opencode.permission` are merged on top of the shared block **per category** (the override wins) and are emitted **only** into `opencode.json` / `opencode.jsonc`; every other tool ignores them. Values may use a bare action string (`"deny"`) or, for OpenCode keys that support fine-grained matching, a pattern map (`{ "*": "ask" }`).\n>\n> ```jsonc\n> {\n> "permission": {\n> "bash": { "git *": "allow", "*": "ask" },\n> },\n> // Emitted only into opencode.json\'s `permission`; never leaks to other tools.\n> "opencode": {\n> "permission": {\n> "external_directory": "deny",\n> },\n> },\n> }\n> ```\n>\n> On **import**, any OpenCode category that is not a shared canonical rulesync category (`bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `opencode` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> You may also override a **shared** category for OpenCode specifically (e.g. put `webfetch` under `opencode.permission` to give OpenCode a different value than the shared block sends to other tools). On generate this works as expected, but note the override is not round-trip stable for shared categories: re-importing the generated `opencode.json` classifies a shared category back into the shared block, so prefer expressing OpenCode-only categories here and keeping cross-tool categories in the shared block.\n\nFor Hermes Agent, permissions are written into the shared `~/.hermes/config.yaml` (global only). Canonical rules map onto the structures Hermes\'s runtime actually enforces:\n\n- `allow` patterns (all categories) → `command_allowlist`.\n- `bash` `deny` patterns → `approvals.deny` — Hermes\'s hard denylist, evaluated **before** `--yolo` / `approvals.mode: off`.\n- `webfetch` `deny` patterns → `security.website_blocklist.domains`.\n- Every `ask` rule, and `deny` rules in categories other than `bash`/`webfetch`, have no native per-pattern Hermes primitive; they survive only for round-trip (Rulesync also stores the full canonical config under a private `permissions.rulesync` key so `.rulesync/permissions.jsonc` reconstructs losslessly).\n\n> **Hermes-only override (`hermes` key):** Hermes exposes approval/security controls with no canonical permission category — e.g. `approvals` (`mode`, `cron_mode`, `mcp_reload_confirm`, ...), `security` (`allow_private_urls`, ...), `skills.write_approval`, `memory.write_approval`. Add a tool-scoped `hermes` override key alongside the shared block to author them; its contents are **deep-merged** into `config.yaml` (so an `approvals.mode` here coexists with the `approvals.deny` derived from canonical deny rules) and are emitted **only** for Hermes. The block is a verbatim passthrough, so any current or future Hermes config key can be set without Rulesync modeling each one. Note that the deep merge replaces **arrays** wholesale, so setting `hermes.approvals.deny` or `hermes.security.website_blocklist.domains` overrides (does not append to) the list derived from the shared `permission` block — use it only when you intend to replace the canonical-derived deny list for Hermes. The top-level `permissions` key is reserved by Rulesync for the round-trip blob, so a `permissions` key inside the `hermes` override is ignored.\n>\n> ```json\n> {\n> "permission": { "bash": { "rm -rf *": "deny" } },\n> "hermes": { "approvals": { "mode": "smart" }, "security": { "allow_private_urls": false } }\n> }\n> ```\n\nFor Codex CLI, this generates a `rulesync` named profile in `.codex/config.toml` under `[permissions.rulesync]` and sets `default_permissions = "rulesync"` (project/global depending on mode). It also generates `.codex/rules/rulesync.rules` from `permission.bash` entries using `prefix_rule(...)`. Current Rulesync-to-Codex mapping supports `bash`, `read`, `edit`/`write`, and `webfetch` categories:\n\n- `bash`: generates one `prefix_rule(...)` per command pattern in `.codex/rules/rulesync.rules` (`allow` → `allow`, `ask` → `prompt`, `deny` → `forbidden`)\n- `read`: `allow` → `read`, `ask`/`deny` → `deny` in `permissions..filesystem`\n- `edit` / `write`: `allow` → `write`, `ask`/`deny` → `deny` in `permissions..filesystem`\n- `webfetch`: `allow`/`deny` map to `permissions..network.domains` (Codex does not support `ask` for domain rules); `network.enabled = true` is emitted only when at least one `allow` rule is present. Deny-only domain sets are emitted without `enabled`, which Codex treats as restricted (its default) while the deny entries still round-trip back into Rulesync rules. Codex rejects the global wildcard `*` in denied domains at config load time, so `webfetch: { "*": "deny" }` is skipped with a warning (unlisted domains are denied by Codex\'s allowlist-first policy anyway); `webfetch: { "*": "allow" }` is emitted as a regular `"*" = "allow"` domain entry, which Codex accepts for denylist-only setups ([openai/codex#15549](https://github.com/openai/codex/pull/15549)). On import, `deny` entries are always taken, while `allow` entries are imported only when `enabled = true` is explicit — Codex treats a missing `enabled` as restricted, so importing an allow entry from a disabled profile would activate a grant Codex never had. A Codex profile with `network.enabled = true` but no `domains` is imported as `webfetch: { "*": "allow" }`, which reflects Codex\'s default semantics where `enabled = true` grants sandbox-wide network access (under Codex\'s experimental `network_proxy` feature, `enabled = true` without an allowlist blocks requests instead, and the regenerated `"*" = "allow"` entry is the closest equivalent).\n\nRelative filesystem globs such as `src/**` or `**/*.tf` are emitted under `permissions..filesystem.":workspace_roots"` instead of the top-level filesystem table, because Codex expects top-level filesystem keys to be absolute paths, `~/...`, or named roots. Rulesync also sets `glob_scan_max_depth = 8` when generated workspace-root rules contain unbounded `**` patterns.\n\nThe `:workspace_roots` table also receives a default `.git` carve-out: `".git/**" = "write"`. Codex\'s `:workspace` baseline keeps `.git` read-only inside workspace roots, which denies basic git workflows (commit/stage operations write to `.git/index`, `.git/objects`, refs, and logs; everyday commands such as `git remote add`, `git push -u`, and local-scope `git config` write to `.git/config`). The write rule reopens the whole subtree, including `.git/config` — an earlier `".git/config" = "read"` security guard (a writable `.git/config` lets a sandboxed process set keys like `core.fsmonitor` or `core.hooksPath` that execute code outside the sandbox) was dropped because it blocked those everyday commands while the protection it added was already partial (`.git/hooks/`, and `.git/modules/**` for submodules, remains writable so hook managers such as lefthook and simple-git-hooks keep working; a sandboxed process could still install a hook directly). Users who want stricter isolation can author a more specific rule (e.g. `read: { ".git/config": "allow" }` or `read: { ".git/hooks/**": "allow" }`) in the canonical permissions, which wins over the default (Codex resolves the more specific path with priority). Because `.git/**` is an unbounded `**` pattern, the carve-out also means `glob_scan_max_depth = 8` is effectively always emitted unless it is suppressed.\n\nThe carve-out is skipped in three cases: a user rule for the same pattern always wins per key; the `codexcli.git_write_rules` override set to `false` suppresses it entirely (only an explicit `false` does; the default is `true`); and it is not injected when `codexcli.base_permission_profile` is `":read-only"` (it would grant `.git` write access inside a sandbox the user explicitly chose to keep read-only) or when the canonical rules contain a direct `":workspace_roots"` pattern (a whole-tree access decision that the defaults must not override). Like `:minimal`, the default-valued carve-out is not imported into the Rulesync model on `rulesync import` — it is re-added on every generate — while customized `.git` values import normally. One limitation: the `git_write_rules` flag itself cannot be recovered from `config.toml`, so it does not round-trip through `rulesync import`; if you opted out with `false`, re-add the flag to the canonical permissions config after importing (and if you want the same `.git` rules while opted out, author them as canonical `read`/`write` rules rather than hand-writing them in `config.toml` — though note that import cannot tell a user-authored `".git/**" = "write"` from the default carve-out, so that exact pattern/value pair is still skipped on import and must be re-authored in the canonical config afterwards). Migration note: configs generated before the `".git/config" = "read"` default was removed still carry that entry, and `rulesync import` now treats it as a user-authored rule — it lands in the canonical config as `read: { ".git/config": "allow" }` and, because Codex gives the more specific path priority, keeps `.git/config` read-only on every regenerate. If you want the current writable default instead, delete that rule from the canonical permissions after importing.\n\nThe generated `[permissions.rulesync]` profile always extends one of Codex\'s built-in permission profiles via `extends`. The baseline is chosen with the `codexcli.base_permission_profile` override key (`":read-only"` | `":workspace"` | `":danger-full-access"`) and defaults to `":workspace"` when unspecified. Codex\'s built-in `:workspace` baseline grants read access to the whole filesystem and write access to the entire workspace root plus `/tmp` and `$TMPDIR` (with carve-outs protecting `.git`, `.codex`, and `.agents`), while `:read-only` keeps command execution read-only; the generated `filesystem` entries then grant or deny access on top of the chosen baseline. Codex\'s third built-in profile, `:danger-full-access`, is rejected by `extends` at Codex config load time — so selecting it works differently: Rulesync emits `default_permissions = ":danger-full-access"` directly and skips the managed `[permissions.rulesync]` profile entirely (with the sandbox removed there is nothing for filesystem/network rules to refine; canonical `read`/`edit`/`write`/`webfetch` rules are ignored for Codex CLI with a warning, and any stale managed profile from a previous generate is pruned while sibling hand-written profiles are preserved). On import, a profile\'s `extends` value round-trips back into `codexcli.base_permission_profile` when it names one of the two extendable built-ins, and a top-level `default_permissions = ":danger-full-access"` round-trips the same way; a custom parent profile is skipped and replaced by the managed baseline on regeneration (with a warning).\n\nRulesync emits `":minimal" = "read"` in the generated filesystem table by default. This enables `include_platform_defaults()` ([FileSystemSpecialPath::Minimal](https://github.com/openai/codex/pull/13434)), which provides the platform/runtime read access needed for basic sandboxed command execution on macOS, Linux, and Windows. `:minimal` is the only special path treated as a fixed baseline: it is always present in the generated table and is never imported into Rulesync\'s own permission model, regardless of its value. A canonical rule for `:minimal` still overrides the emitted value on generate (e.g. a `write: { ":minimal": "allow" }` rule emits `":minimal" = "write"` — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for when that is needed), but because import always skips `:minimal`, such a customization does not round-trip: after `rulesync import`, re-author the rule or the next generate falls back to `"read"`. The other special paths `:root`, `:tmpdir`, and `:slash_tmp` are user-managed access rules that are imported into the Rulesync model and re-emitted from it like any ordinary filesystem entry (`:root = "deny"` becomes a read/edit deny, `:tmpdir = "write"` becomes an edit allow, and so on). Because they round-trip through `.rulesync/permissions.jsonc` rather than relying on an existing `.codex/config.toml`, a restrictive value such as `:root = "deny"` survives a fresh-clone `rulesync generate` with no pre-existing Codex config.\n\n`network.mode`, `network.unix_sockets`, and `description` have no equivalent in Rulesync\'s canonical permissions model and are not generated. If an existing `.codex/config.toml` already contains these fields on the `rulesync` profile, Rulesync preserves them on regeneration — as it does any other network key it does not model (e.g. `dangerously_allow_all_unix_sockets` or Codex\'s proxy keys), since network settings are user territory by design. `network.enabled` is only half-managed: Rulesync sets `enabled = true` itself when the canonical model contains an allow domain, but when a regeneration computes no `enabled` value, a user-authored `enabled` is preserved (with a warning) instead of being deleted — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for the recommended user-managed entries. The preservation applies only when the existing profile carries no allow domain: an existing `enabled` next to allow domains is Rulesync\'s own managed output, so removing every webfetch allow rule from the canonical model removes `enabled` too (falling back to Codex\'s restricted default) instead of leaving an unscoped `enabled = true` behind. Note that `filesystem`, `network.domains`, and `extends` are always managed by Rulesync (`filesystem`/`network.domains` derived from `edit`/`write`/`webfetch` rules, `extends` from `codexcli.base_permission_profile`), so hand-authored values in those fields will be replaced on regeneration.\n\n> **Codex CLI-only override (`codexcli` key):** Codex CLI\'s permission surface is richer than the canonical allow/ask/deny model — its approval workflow, permission-profile baseline, and per-app tool gating have no canonical category. Add a tool-scoped `codexcli` override to author them: except for `base_permission_profile`, its fields are written verbatim as **top-level `.codex/config.toml` keys** (the override wins per key; existing sibling keys the user set directly are preserved, and table values are shallow-merged) while the shared `permission` block keeps driving the managed `[permissions.rulesync]` profile and `default_permissions`. Supported keys: `base_permission_profile` (`:read-only` | `:workspace` | `:danger-full-access`, default `:workspace` — not a top-level key; it becomes the managed profile\'s `extends` baseline, or with `:danger-full-access` the directly-selected `default_permissions` value, see above), `approval_policy` (`untrusted` | `on-request` (legacy alias `on-failure`) | `never`, or a `{ granular = { … } }` table kept verbatim; defaults to `on-request` when neither the override nor the existing config sets it), `apps` (per-app tool gating — `apps..tools..approval_mode` / `.enabled`, `apps..default_tools_approval_mode`), `approvals_reviewer` (`user` | `auto_review` (legacy alias `guardian_subagent`), or a table; defaults to `auto_review` when neither the override nor the existing config sets it), and `git_write_rules` (boolean, default `true` — like `base_permission_profile` it is not a top-level key: it controls whether the managed profile\'s `:workspace_roots` table emits the default `.git` carve-out described above; only an explicit `false` suppresses it). **Deprecated:** `sandbox_mode` (`read-only` | `workspace-write` | `danger-full-access`) with the sibling `sandbox_workspace_write` table (`network_access`, `writable_roots`, …) belong to Codex\'s classic sandbox system, which permission profiles supersede — Codex prioritizes these legacy keys over permission profiles when both are present, so authoring them disables the generated `[permissions.rulesync]` profile; they are still accepted (with a warning) so existing configs round-trip, but use `base_permission_profile` and the shared `permission` block instead. On import, the top-level keys round-trip back into the `codexcli` override, and the managed profile\'s `extends` round-trips into `base_permission_profile`. It is a `looseObject`, so future top-level Codex config keys can be authored here (merged verbatim on generate; only the listed keys are re-extracted on import). Example: `{ "permission": { … }, "codexcli": { "base_permission_profile": ":workspace", "approval_policy": "on-request", "approvals_reviewer": "auto_review" } }`. **Out of scope:** `mcp_servers.*` per-MCP gating is **not** authorable here — it is owned by the MCP feature (`codexcli-mcp.ts` writes the `mcp_servers` tables in the same `config.toml`), and `permissions` / `default_permissions` are owned by the canonical model; any such key placed in the override is skipped with a warning. See the [Codex configuration reference](https://developers.openai.com/codex/config-reference) and [permissions docs](https://developers.openai.com/codex/permissions).\n\nFor Kiro, this generates tool permission settings in `.kiro/agents/default.json` (project mode):\n\n- `bash` maps to `toolsSettings.shell.allowedCommands` / `toolsSettings.shell.deniedCommands`\n- `read` maps to `toolsSettings.read.allowedPaths` / `toolsSettings.read.deniedPaths`\n- `edit` / `write` map to `toolsSettings.write.allowedPaths` / `toolsSettings.write.deniedPaths`\n- `grep` maps to `toolsSettings.grep.allowedPaths` / `toolsSettings.grep.deniedPaths`\n- `glob` maps to `toolsSettings.glob.allowedPaths` / `toolsSettings.glob.deniedPaths` (both emitted only when a rule is present, so existing configs do not gain empty tables)\n- `webfetch` / `websearch` with pattern `*` map to `allowedTools` entries (`web_fetch` / `web_search`)\n- `ask` rules are skipped with a warning (Kiro config does not support explicit ask entries)\n\n> **Kiro-only override (`kiro` key):** Kiro\'s agent config exposes per-tool `toolsSettings` knobs with no canonical allow/ask/deny category. Author them through a tool-scoped `kiro` override under `toolsSettings`: the shell auto-trust flags `shell.autoAllowReadonly` / `shell.denyByDefault`, the `aws` built-in tool\'s `allowedServices` / `deniedServices` (+ `autoAllowReadonly`), and the `web_fetch` domain trust arrays `trusted` / `blocked` (regex host patterns; Kiro documents these for `web_fetch` only — `web_search` has no domain-trust surface). Example: `{ "permission": { … }, "kiro": { "toolsSettings": { "shell": { "autoAllowReadonly": true }, "aws": { "allowedServices": ["s3"], "deniedServices": ["eks"] }, "web_fetch": { "trusted": [".*github\\\\.com.*"] } } } }`. The override is **deep-merged per `toolsSettings` key** (the override wins at the leaf) so authoring `shell.autoAllowReadonly` keeps the canonical-generated `shell.allowedCommands`; the shared `permission` block keeps driving `shell.{allowed,denied}Commands`, `read`/`write`/`grep`/`glob` paths, and the `web_fetch`/`web_search` `allowedTools` toggles. Existing non-canonical `shell` flags are preserved across regenerate even without an override. On **import**, these Kiro-specific surfaces are lifted into the `kiro` override so they round-trip. It is a `looseObject` at every level, so future Kiro `toolsSettings` fields pass through verbatim. Kiro MCP `disabledTools` lives in the separate `.kiro/settings/mcp.json` file and is modeled by the MCP feature; MCP `autoApprove` remains outside this permissions translator. See the [Kiro built-in tools](https://kiro.dev/docs/cli/reference/built-in-tools/) and [configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/) docs.\n\nFor Cursor CLI, this generates `permissions` entries in `.cursor/cli.json` (project mode) or `~/.cursor/cli-config.json` (global mode). Cursor CLI only supports `allow` and `deny` decisions, so `ask` rules are skipped with a warning. Tool categories are mapped to PascalCase Cursor tool names (`bash` → `Shell`, `read` → `Read`, `edit`/`write` → `Write`, `webfetch` → `WebFetch`, `mcp__*` → `Mcp`). Existing Cursor-specific entries that Rulesync does not manage (for example, MCP entries with extra fields) are preserved on round-trip.\n\n> **Cursor-only override (`cursor` key):** Cursor\'s `cli.json` carries scalar autonomy settings with no canonical permission category — `approvalMode` (`allowlist` | `auto-review` | `unrestricted`) and a `sandbox` object (`mode`/`networkAccess`). Add a tool-scoped `cursor` override to author them: its fields are merged into the top level of `cli.json` while the shared `permission` block keeps driving the `permissions.allow`/`permissions.deny` arrays (the override cannot clobber that managed block). On import, `approvalMode` and `sandbox` round-trip back into the `cursor` override. It is a `looseObject`, so `sandbox`\'s (currently undocumented) value set passes through verbatim and extra `cli.json` keys can be authored here (they are merged verbatim on generate); note that only `approvalMode` and `sandbox` are re-extracted on import.\n>\n> ```json\n> {\n> "permission": { "bash": { "git *": "allow" } },\n> "cursor": { "approvalMode": "auto-review" }\n> }\n> ```\n>\n> The separate Cursor **IDE** `permissions.json` (`mcpAllowlist`, `terminalAllowlist`, `autoRun.*`) is a different file and is not targeted by this translator.\n\nFor GitHub Copilot (`copilot`), this manages the three `chat.tools.*.autoApprove` maps in the workspace `.vscode/settings.json` (project mode only). VS Code has no standalone, environment-agnostic Copilot policy file, so project-level auto-approvals are configured through VS Code Copilot Chat\'s workspace settings. Three canonical categories have a clean, non-lossy mapping and are emitted: `bash` → `chat.tools.terminal.autoApprove` (command patterns), `edit` → `chat.tools.edits.autoApprove` (file globs) and `webfetch` → `chat.tools.urls.autoApprove` (URL patterns). In all three, `allow` → `true` (auto-approve) and `deny` → `false` (never auto-approve); an `ask` rule is represented by **omitting** the entry, so VS Code falls through to its default in-chat approval prompt. The canonical `read` category has no VS Code approval surface, and `write` is deliberately **not** folded into the edits map alongside `edit` — doing so would make the two indistinguishable on import — so neither is emitted. VS Code also accepts a `{ "approveRequest": …, "approveResponse": … }` object per URL pattern; that form has no canonical equivalent, so it is skipped on import, and because Rulesync owns the key outright it is replaced whenever the canonical config carries any `webfetch` rule. `.vscode/settings.json` is a general workspace file (JSONC), so Rulesync merges only those three keys non-destructively and never deletes the file; every unrelated setting is preserved. VS Code\'s user-scope `settings.json` lives at a platform-dependent path outside Rulesync\'s home-relative global model, so only project scope is supported. The all-or-nothing `chat.tools.global.autoApprove` boolean and the registry-allowlist `chat.mcp.access` setting are intentionally **not** mapped, since collapsing per-pattern rules into them would misrepresent what was configured. See the [VS Code agent approvals docs](https://code.visualstudio.com/docs/agents/approvals) and the [edit-approval docs](https://code.visualstudio.com/docs/copilot/chat/review-code-edits).\n\nFor Kilo Code, this generates the `permission` object in `kilo.jsonc` (project mode) or `~/.config/kilo/kilo.jsonc` (global mode). The shape is identical to OpenCode\'s (Kilo is an OpenCode fork), so categories like `bash`, `read`, `edit`, `write`, `webfetch`, and `mcp` accept either a string catch-all (`"allow" | "ask" | "deny"`) or a `{ : }` map. Other top-level keys in `kilo.jsonc` are preserved on round-trip. **The `permission` object is merged per top-level tool key**: for each tool key present in the rulesync output, that key is replaced entirely from rulesync (rulesync owns its managed keys; manual edits inside a managed key will be overwritten on the next generation). Tool keys that exist in the existing `kilo.jsonc` but are NOT in the rulesync output are preserved verbatim so user-added Kilo-only categories survive regeneration. When a regenerate replaces a key whose existing value contained `deny` patterns that disappear from the new rulesync output, an aggregated `logger.warn` enumerates the dropped patterns (matching the project convention used by every other permissions translator). Edits to other top-level keys (e.g. `model`) are preserved. **Malformed `kilo.jsonc` aborts the run**: the `jsonc-parser` library would otherwise silently coerce a syntax error to `{}` and overwrite the corrupted file with an empty `permission`, dropping the user\'s existing `deny` rules. Rulesync now surfaces parse errors so the run aborts before any destructive write — matching the strict `JSON.parse` behavior used by every other permissions translator.\n\n> **Kilo-only override (`kilo` key):** Kilo\'s `permission` object carries tool-specific keys with no canonical permission category — OpenCode-inherited ones (`external_directory`, `doom_loop`, `lsp`, `question`, `todowrite`, `skill`, `task`, `list`) and Kilo-unique ones (`agent_manager`, `notebook_read`, `notebook_edit`, `notebook_execute`, `repo_clone`, `repo_overview`). Add a tool-scoped `kilo` override key alongside the shared block (mirroring the `opencode` override) to author these; entries under `kilo.permission` are merged on top of the shared block **per key** (the override wins) and are emitted **only** into `kilo.jsonc`. Each value may be a bare action string or a pattern map. On **import**, any Kilo key that is not a shared canonical category (`bash`, `read`, `edit`, `webfetch`, `websearch`, `grep`, `glob`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `kilo` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> **Kilo-only override (`kilo.sandbox`):** the `sandbox` block Kilo runs commands in is a security surface orthogonal to per-tool allow/ask/deny, with no canonical category, so it is authored under the same tool-scoped `kilo` override: `enabled` (boolean), `network` (e.g. `"deny"`), `allowed_hosts` (a list of `host` / `host:port` destination exceptions) and `writable_paths`. It is shallow-merged into the top-level `sandbox` key of `kilo.jsonc` — the override\'s keys win, unrelated sibling keys you set directly are preserved — and the whole block round-trips back into `kilo.sandbox` on import. **Scope matters here.** Kilo honors `allowed_hosts` and `writable_paths` from the _global_ config only, and lets a project config merely tighten (`enabled: true`, `network: "deny"`); a project-level network denial even clears the global destination exceptions. Rulesync mirrors that rather than writing config Kilo would ignore: at project scope only `enabled` and `network` are emitted, and any other key is dropped with a warning telling you to author it with `--global`. See the [sandboxing docs](https://kilo.ai/docs/getting-started/settings/sandboxing).\n\n> **Name-mismatch traps.** Canonical category names do not always match Kilo\'s key names: Kilo folds **`write` into `edit`** (there is no `write` key), uses **`notebook_edit`** (not the canonical `notebookedit`) and **`task`/`agent_manager`** (not `agent`), and has **no `mcp` key** (MCP is addressed via `mcp__*` tool-name keys). Rulesync passes key names through verbatim, so author Kilo keys using Kilo\'s own names (e.g. put a `notebook_edit` rule under `kilo.permission`, not the canonical `notebookedit`). Kilo also treats a `null` action as a delete sentinel; Rulesync does not model `null` and only round-trips `allow`/`ask`/`deny`.\n\nFor AugmentCode CLI, this generates `toolPermissions` entries in `.augment/settings.json` (project mode) or `~/.augment/settings.json` (global mode). Each entry has `toolName`, an optional `shellInputRegex` (only for shell commands), and `permission.type` ∈ `"allow" | "deny" | "ask-user"`. Tool category mapping: `bash` → `launch-process`, `read` → `view`, `edit` → `str-replace-editor`, `write` → `save-file`, `webfetch` → `web-fetch`, `websearch` → `web-search`. Action mapping: rulesync `ask` → AugmentCode `ask-user`. For `bash` patterns other than `*`, the glob pattern is converted to a regex and emitted as `shellInputRegex`. The glob → regex conversion maps `*` to `.*`, `?` to `.`, escapes `\\^$.|+(){}[]`, and anchors at both ends; characters outside that set (notably `-`, `/`, `:`, `,`) are emitted verbatim, so Augment will match them literally. Generated entries are sorted **deny first, ask second, allow last**, with more specific patterns (those carrying `shellInputRegex`) before catch-alls — this is required because Augment\'s `toolPermissions` is evaluated **first-match-wins**. Existing `toolPermissions` entries whose `toolName` is NOT in the rulesync-managed set are preserved on round-trip; existing **`deny` entries for ANY managed `toolName`** (`launch-process`, `view`, `str-replace-editor`, `save-file`, `web-fetch`, `web-search`) are also preserved (fail-closed) so a user-added deny rule on any managed tool cannot be silently downgraded by regeneration. Existing managed-tool `allow` / `ask-user` entries are still replaced (rulesync owns the permissive surface for managed namespaces). **Non-bash categories do not have a documented per-input matcher in AugmentCode**, so Rulesync emits at most one catch-all entry per tool: if the rulesync category contains any `deny` rule, Rulesync emits a single `deny` entry for the entire tool (fail-closed) and warns; otherwise only `*`-pattern allow/ask rules are emitted and any non-`*` allow/ask patterns are dropped with a warning. Importing AugmentCode entries back into rulesync recovers `bash` patterns from `shellInputRegex` but the other categories always import as the catch-all `*` pattern. **The import direction also applies fail-closed precedence** when multiple existing entries collapse to the same `(canonical, "*")` key (e.g. `[{view: deny}, {view: allow}]`): the most restrictive action wins regardless of iteration order (precedence: `deny` > `ask` > `allow`), so a user-added deny in the source file is never silently dropped by import order. The `launch-process` (bash) path is unchanged because each entry has its own `shellInputRegex`-derived pattern with no `"*"` collapse. On **import** (project scope), Rulesync also reads the layered overrides file `/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before converting to the canonical model, following Auggie\'s documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including `toolPermissions`, which Auggie concatenates local-first under first-match — are combined across tiers), so personal permission overrides are picked up without dropping a committed base `deny`. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json` (it stays a user-owned, gitignored file), and AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode. An unknown top-level key such as `recommendedMarketplaces` (added in Auggie CLI 0.20.0) is preserved verbatim through the generate round-trip via the `{...settings}` merge.\n\n> **AugmentCode-only override (`augmentcode` key):** AugmentCode\'s `toolPermissions[]` supports "custom policy" entries the canonical allow/ask/deny model cannot express — `permission.type` of `webhook-policy` / `script-policy` (delegating the decision to a `webhookUrl` / `script`) and an `eventType` of `tool-response` (a post-execution check rather than the default pre-execution `tool-call`). Author these through a tool-scoped `augmentcode` override with a `toolPermissions` array of verbatim entries: `{ "permission": { … }, "augmentcode": { "toolPermissions": [ { "toolName": "github-api", "permission": { "type": "webhook-policy", "webhookUrl": "https://api.example.com/validate" } }, { "toolName": "view", "eventType": "tool-response", "permission": { "type": "allow" } } ] } }`. Authored entries are **prepended** — ahead of the canonical-generated basic rules — so a webhook/script gate or tool-response check is never shadowed by a regenerated allow/deny/ask entry under first-match-wins. When the override authors `toolPermissions` it becomes the source of truth for the special entries (the existing file\'s specials are no longer separately preserved, avoiding a double-emit); without an override, any special entries already present in `settings.json` are preserved verbatim as before. On **import**, special entries are lifted verbatim into the `augmentcode` override (rather than being skipped with a warning) so they round-trip and become user-authorable; basic entries continue to drive the shared `permission` block. The entry objects stay a loose passthrough so `shellInputRegex`, `webhookUrl`, `script`, and future non-policy fields survive untouched, while the documented bounded fields are validated as enums: `permission.type` (`allow` | `deny` | `ask-user` | `webhook-policy` | `script-policy`) and `eventType` (`tool-call` | `tool-response`). Both project and global scope are supported.\n\nFor Factory Droid, this generates `commandAllowlist` / `commandDenylist` arrays in `.factory/settings.json` (project mode) or `~/.factory/settings.json` (global mode). Factory Droid only gates **shell commands** through these two lists, so only the rulesync `bash` category is translated: `allow` patterns become `commandAllowlist` entries (run without confirmation) and `deny` patterns become `commandDenylist` entries (always require confirmation; the denylist wins when a command is in both). Factory Droid has **no separate `ask` list** — any command not in the allowlist already prompts — so rulesync `ask` rules are dropped. Categories other than `bash` cannot be represented in the command allow/deny model and are skipped, with a `logger.warn` when a skipped category carries a `deny` rule (to surface the gap). rulesync owns the `commandAllowlist` / `commandDenylist` keys (they are replaced from the rulesync output), while every other key in `settings.json` (e.g. `hooks`) is preserved verbatim on round-trip — except the Factory-specific security keys covered by the `factorydroid` override below, which are lifted into that override on import. Importing reads the two lists back into the `bash` category.\n\n> **Factory Droid-only override (`factorydroid` key):** Factory Droid has security controls that do not fit the per-command `allow`/`ask`/`deny` model — the hard-block `commandBlocklist` tier (commands that can **never** run, not even under full autonomy — distinct from an approvable `deny`), plus `networkPolicy` (`allowedIps`), `sandbox` (`enabled`/`mode`/`filesystem`/`network`), `mcpPolicy`, `enableDroidShield`, autonomy settings (`sessionDefaultSettings`, `maxAutonomyLevel`, `interactionMode`), the plugin-bootstrap keys `extraKnownMarketplaces` / `enabledPlugins` (Droid auto-registers those marketplaces and installs those plugins on start — the upstream distribution path for the same artifacts rulesync generates), and the `hooksDisabled` kill-switch. Add a tool-scoped `factorydroid` override to author them: its keys are merged into `settings.json` (the override wins) while the shared `permission` block keeps driving `commandAllowlist`/`commandDenylist`. On **import**, these keys are lifted into the `factorydroid` override — so `commandBlocklist` now round-trips faithfully (its never-runs guarantee is preserved) rather than being collapsed onto an approvable `deny`.\n>\n> ```json\n> {\n> "permission": { "bash": { "git *": "allow" } },\n> "factorydroid": { "commandBlocklist": ["curl *"], "sandbox": { "enabled": true } }\n> }\n> ```\n\nFor Cline CLI, this generates `.cline/command-permissions.json` (project mode only). Cline reads this file via the `CLINE_COMMAND_PERMISSIONS` environment variable; you can wire it up with `export CLINE_COMMAND_PERMISSIONS=$(cat .cline/command-permissions.json)`. The schema is `{ "allow": [...], "deny": [...], "allowRedirects": false }`. Cline only supports shell commands and only `allow`/`deny`. Non-`bash` categories are dropped and rulesync `ask` rules for `bash` are **translated to `deny`** (fail-closed safety, since Cline lacks `ask` semantics); both translation notices are surfaced via a single aggregated `logger.warn` per generation (matching the project convention used by every other permissions translator) so the translation stays visible without tripping CI gates that treat error lines as failures. **The `allow` array is wholesale-replaced by rulesync** — user-added entries inside `allow` are not preserved on regenerate. **The `deny` array is additive** — user-added denies in the existing file are preserved on every generation alongside the rulesync-derived denies (fail-closed standard). The `allowRedirects` field (a single global boolean gating shell redirection operators `>`/`>>`/`<`) can be authored from rulesync via a tool-scoped **`cline` override** — add `"cline": { "allowRedirects": true }` alongside the shared `permission` block. Precedence: the `cline` override wins, otherwise the existing file value is preserved, otherwise it defaults to `false`. On import, a `true` value round-trips back into the `cline` override (the default `false` emits no override). Cline does not have a stable per-user file location for command permissions, so global mode is not supported. If a pattern ends up in **both** `allow` and `deny` (defensive check; not reachable from a single rulesync config), Rulesync emits a warning because Cline does not document a deterministic deny-priority.\n\nFor Zed, this generates the `agent.tool_permissions` object in `.zed/settings.json` (project mode) or `~/.config/zed/settings.json` (global mode — `%APPDATA%\\Zed\\settings.json` on Windows). Each canonical category becomes a key under `agent.tool_permissions.tools.` (tool-name mapping: `bash` → `terminal`, `read` → `read_file`, `edit` → `edit_file`, `write` → `write_file`, `webfetch` → `fetch`, `websearch` → `search_web`; unknown categories, including `mcp::` keys, pass through unchanged). The canonical `*` category is the exception: its catch-all `*` rule sets the top-level `agent.tool_permissions.default` — rung 6 of Zed\'s precedence ladder, and the mechanism Zed documents for MCP tools — rather than an inert `tools["*"]` entry (`*` is not a Zed tool name; a stale `tools["*"]` entry written by an earlier version is cleaned up when the canonical config carries a `*` category, and the `default` imports back as `*: { "*": }`). Pattern-scoped rules in the `*` category have no Zed counterpart and are dropped with a warning. Within every other category, the catch-all `*` pattern sets the per-tool `default`, while specific patterns become `always_allow` / `always_deny` / `always_confirm` entries of the form `{ "pattern": , "case_sensitive": false }`. Action mapping: rulesync `ask` ⇄ Zed `confirm` (`allow`/`deny` are shared). Because Zed matches with regular expressions, patterns are emitted verbatim — author canonical patterns as regexes when targeting Zed. The settings file is shared with the MCP (`context_servers`) and ignore (`private_files`) features, so writes merge non-destructively: unrelated settings, a user-set `agent.tool_permissions.default` (when the canonical config has no `*` category), and any `tools.` entries NOT managed by rulesync are preserved on round-trip. The canonical model has no slot for per-pattern case sensitivity, so rulesync always emits `case_sensitive: false`; a hand-authored `case_sensitive: true` on a rulesync-managed tool is overwritten on the next generate.\n\nFor Qwen Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.qwen/settings.json` (project mode) or `~/.qwen/settings.json` (global mode). The format mirrors Claude Code\'s: entries are `Bash()`, `Read()`, `Edit()`, `Write()`, `WebFetch()`, `WebSearch()`, `Grep()`, `Glob()`, `Agent()`, etc. Other top-level keys in `settings.json` are preserved on round-trip. Patterns may contain nested parentheses (e.g. `Bash(echo (a))`); Rulesync uses the **last** `)` as the closing delimiter when parsing, so inner parens round-trip. Malformed entries (missing closing paren, trailing characters) emit a warning; for **`deny`** they fall back to the catch-all pattern `*` (fail-closed: broadening a deny is the safer direction), but for **`allow` / `ask`** they are **dropped** rather than broadened — silently turning a narrow user rule into `*` would be a fail-open round-trip. Generation does not create the `.qwen/` directory until `writeAiFiles` runs, so dry-run is side-effect-free.\n\nFor Kimi Code, permissions are global-only and generate `[[permission.rules]]` entries in `~/.kimi-code/config.toml`. Canonical categories map to Kimi tool patterns (`bash` → `Bash`, `read` → `Read`, `write` → `Write`, `edit` → `Edit`, `grep` → `Grep`, `glob` → `Glob`, `websearch` → `WebSearch`, `webfetch` → `FetchURL`, `agent` → `Agent`, and `mcp__…` passes through as the MCP tool name); a `*` canonical pattern emits the bare tool name and a specific pattern emits `Tool(pattern)`. Actions map 1:1 to Kimi\'s `allow` / `ask` / `deny`, and generated rules use `scope = "user"`. Kimi evaluates rules first-match-wins, so Rulesync sorts canonical output fail-closed: all `deny` rules precede `ask`, all `ask` rules precede `allow`, and more-specific patterns precede broader patterns within each action. Kimi does not match MCP tool arguments; an argument-specific MCP `allow`/`ask` is skipped with a warning rather than broadened, while an argument-specific `deny` becomes a whole-tool deny with a warning. The optional `kimi-code.defaultPermissionMode` override writes Kimi\'s top-level `default_permission_mode` (`manual` / `yolo` / `auto`), while `kimi-code.rules` accepts native rules that canonical categories cannot express and emits them first in their authored order. On import, Rulesync preserves the complete ordered rule list under `kimi-code.rules`, including rules that could otherwise fit the shared permission model, so regeneration cannot change Kimi\'s first-match behavior. A `kimi-code.tools` override writes Kimi\'s `[tools] enabled` / `disabled` lists — a separate enforcement layer from `[[permission.rules]]`, since a rule prompts while these remove the tool from every agent in every session. Entries pass through verbatim because the section uses agent-file tool syntax (exact built-in names, `mcp__server__*` globs) rather than the canonical category/pattern shape. Note that Kimi registers `[tools]` in its v2 engine, so today it applies under `kimi web` and experimental `kimi -p` rather than the interactive TUI. Like the MCP defaults, the section merges per key: authoring only `enabled` leaves a hand-written `disabled` list alone, and dropping the override leaves the section as it stands. Values are carried through exactly as written, empty lists included — `enabled = []` is an allowlist admitting _nothing_, the strictest setting there is, while an absent `enabled` means no allowlist at all, so the two are never interchanged. The TOML file is shared with hooks, the MCP timeout defaults and other Kimi settings, so updates merge in place and never delete the file. See the [Kimi Code permission docs](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html).\n\n> **Qwen-only override (`qwencode` key):** Qwen\'s `settings.json` exposes autonomy/sandbox controls with no canonical permission category — under `tools` (`approvalMode` = `plan`/`default`/`auto-edit`/`auto`/`yolo`, `autoAccept`, `sandbox`, `sandboxImage`, `disabled`, `visible` — the deferred-tool startup visibility list, union-merged by Qwen across scopes), `security` (`folderTrust`), and `permissions.autoMode` (the Auto Mode classifier config: `hints.{allow,softDeny,hardDeny}`, `environment`, `classifyAllShell`). Add a tool-scoped `qwencode` override to author them: `qwencode.tools` and `qwencode.security` are shallow-merged into the matching `settings.json` group at the **top level of that group** (an unrelated sibling key such as `tools.core` is preserved, an override key wins, and a nested object the override supplies such as `security.folderTrust` replaces the existing one wholesale rather than being deep-merged), while `qwencode.autoMode` is emitted as `permissions.autoMode` (replacing the existing `autoMode` wholesale) and the shared `permission` block keeps driving the `permissions.allow`/`ask`/`deny` arrays. On import, the documented autonomy keys (`tools.{approvalMode,autoAccept,sandbox,sandboxImage,disabled,visible}`, `security.folderTrust`, and `permissions.autoMode`) round-trip back into the override; other `tools`/`security` keys are left in `settings.json` and not extracted.\n>\n> ```json\n> {\n> "permission": { "bash": { "*": "allow" } },\n> "qwencode": {\n> "tools": { "approvalMode": "auto-edit" },\n> "security": { "folderTrust": { "enabled": true } },\n> "autoMode": { "hints": { "allow": ["Running tests"] }, "classifyAllShell": true }\n> }\n> }\n> ```\n>\n> **Alias overlap:** Qwen\'s `Read` is a meta-tool that also covers grep/glob/list, so canonical `grep`/`glob` rules are emitted as their own `Grep(...)`/`Glob(...)` entries but overlap Qwen\'s `Read` category at runtime; and Qwen folds web search into `web_fetch`, so a canonical `websearch` rule (`WebSearch(...)`) may not correspond to a distinct Qwen tool. `tools.disabled` is a hard whole-tool disable (stronger than `deny`) and is only authorable via the override, not the canonical `deny`.\n\nFor Warp, this generates the command allow/deny regex lists in Warp\'s global user `settings.toml` (**global mode only** — Warp has no project-scoped permissions file). Since Warp promoted file-backed execution profiles to Stable (2026-07-28), the surface runtime enforcement actually reads is the `command_allowlist` / `command_denylist` arrays of the `default` record under `[agents.execution_profiles.]`; rulesync merges the lists into that `default` profile **in place** whenever the collection exists, preserving every other profile key and every other profile ID. The legacy `agent_mode_command_execution_allowlist` / `agent_mode_command_execution_denylist` keys under `[agents.profiles]` are still written for un-migrated installs and old clients — but on a migrated install they are inert (Warp consumes them only once during its one-shot migration). When the `[agents.execution_profiles]` collection does not exist yet, rulesync deliberately does **not** create it: on such an un-migrated install the legacy keys are still live, and creating the collection would mark Warp\'s migration complete early and strand the user\'s other legacy settings. Note that rulesync manages only the `default` profile — if a different execution profile is active in Warp, the generated lists (including `deny` rules) are not enforced until the user switches back to `default`. The settings file path differs per platform: macOS `~/.warp/settings.toml`, Linux `~/.config/warp-terminal/settings.toml`, Windows `%LOCALAPPDATA%\\warp\\Warp\\config\\settings.toml`. Only the `bash` category maps (`allow` → allowlist, `deny` → denylist); Warp matches commands with **regular expressions**, so patterns are emitted verbatim — author canonical `bash` patterns as regexes when targeting Warp (mirrors Zed). Warp has no per-command `ask` list, so `ask` rules are dropped, and non-`bash` categories are skipped (with a warning when they carry `deny` rules). On import, the `default` execution profile\'s lists are preferred (falling back to the legacy keys when no collection exists), and a pattern present in both lists resolves to `deny` (Warp\'s denylist wins). Both blocks are merged into the existing `settings.toml`, preserving other Warp settings, and the file is never deleted. **rulesync owns the command lists** (it is the source of truth): they are replaced from the rulesync config on each `--global` generate, so a manually curated Warp allowlist/denylist not mirrored in `.rulesync/permissions.jsonc` is overwritten — keep command permissions in rulesync (run `rulesync import` first to capture an existing hand-curated list). MCP allow/deny is a separate Warp surface not modeled here. See the [Warp agent profiles & permissions docs](https://docs.warp.dev/agent-platform/capabilities/agent-profiles-permissions/).\n\n> **Warp-only override (`warp` key):** Warp\'s `[agents.profiles]` table also exposes file-read/read-only autonomy knobs that do not fit the per-command `allow`/`ask`/`deny` model — `agent_mode_coding_permissions` (`always_ask_before_reading` / `always_allow_reading` / `allow_reading_specific_files`), `agent_mode_coding_file_read_allowlist` (an array of paths the agent may read), and `agent_mode_execute_readonly_commands` (a boolean auto-executing read-only commands). Add a tool-scoped `warp` override to author them: its keys are merged into `[agents.profiles]` (the override wins) while the shared `permission` block keeps driving the command lists. On **import**, these keys are lifted from `settings.toml` into the `warp` override, so they round-trip faithfully instead of being dropped. These legacy autonomy keys are part of Warp\'s one-shot migration, so on a migrated install they are inert; their execution-profile counterparts are authored through the nested `warp.execution_profile` block instead — `read_files` / `apply_code_diffs` / `execute_commands` / `mcp_permissions` (each `agent_decides` / `always_allow` / `always_ask`), `write_to_pty` (`always_allow` / `always_ask` / `ask_on_first_write`), `ask_user_question` (`never` / `ask_except_in_auto_approve` / `always_ask`), `run_agents` (`never_allow` / `always_allow` / `always_ask`), `computer_use` (`never` / `always_ask` / `always_allow`), `directory_allowlist` (paths readable without approval), and `mcp_allowlist` / `mcp_denylist` (MCP server IDs). Its keys are merged into the `default` record of `[agents.execution_profiles.]` under the same guard as the command lists (only when the collection already exists — creating it would complete Warp\'s migration early; a warning is logged and the block skipped on an un-migrated install), unknown keys pass through verbatim for forward compatibility (export-only: import lifts back exactly the permission keys listed above, while profile-management keys such as `name` or the model overrides never round-trip), and the rulesync-owned `command_allowlist`/`command_denylist` always win. Example:\n>\n> ```json\n> {\n> "permission": { "bash": { "git .*": "allow" } },\n> "warp": {\n> "agent_mode_coding_permissions": "always_allow_reading",\n> "agent_mode_execute_readonly_commands": true,\n> "execution_profile": {\n> "read_files": "always_allow",\n> "directory_allowlist": ["/home/me/projects"],\n> "mcp_denylist": ["untrusted-server"]\n> }\n> }\n> }\n> ```\n>\n> See the [Warp settings reference](https://docs.warp.dev/terminal/settings/all-settings/).\n\nFor the Antigravity IDE, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the committable workspace `.antigravity/settings.json` (**project mode only**). Antigravity 2.0 evaluates these `Deny > Ask > Allow` and uses `action(target)` entries; rulesync maps canonical categories onto the IDE action vocabulary: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the IDE-only `execute_url` / `unsandboxed` actions have no canonical equivalent and pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` file holds other workspace settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. The User-scope settings file is a platform-dependent VS-Code-style path outside rulesync\'s home-relative global model, so **global mode is not supported**; the workspace file is intended to be checked into git. See the [Antigravity permissions docs](https://antigravity.google/docs/permissions).\n\nFor the Antigravity CLI (`agy`), this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the global `~/.gemini/antigravity-cli/settings.json` (**global mode only**). The CLI shares Antigravity 2.0\'s Fine-Grained Permissions Engine with the IDE, so the same `action(target)` vocabulary and `Deny > Ask > Allow` precedence apply: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the engine-only `execute_url` / `unsandboxed` actions pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` holds other CLI settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. Four CLI-only autonomy/sandbox knobs outside the allow/ask/deny arrays can be authored (and round-trip) through an optional `antigravity-cli` override block in `.rulesync/permissions.jsonc`: `toolPermission` (the global autonomy preset — `request-review` (default) / `proceed-in-sandbox` / `always-proceed` / `strict`), `enableTerminalSandbox` (a boolean confining agent-run commands to OS containment), `artifactReviewPolicy` (whether the agent\'s artifact changes are gated on a review prompt — `asks-for-review` (default) / `agent-decides` / `always-proceed`) and `allowNonWorkspaceAccess` (a boolean, off by default, letting the agent read or write files outside the active workspace roots). Antigravity applies the allow/deny lists as per-rule exceptions to the preset at runtime, so rulesync authors these keys verbatim as top-level siblings of `permissions` with no precedence modeling. This override is **CLI-only** — the Antigravity IDE exposes the same concepts through a GUI with no documented JSON schema, so it does not apply to `antigravity-ide`. Example: `{ "permission": { … }, "antigravity-cli": { "toolPermission": "strict", "enableTerminalSandbox": true, "artifactReviewPolicy": "agent-decides", "allowNonWorkspaceAccess": false } }`. Verified against the [Antigravity CLI reference](https://antigravity.google/docs/cli/reference), [sandbox docs](https://antigravity.google/docs/cli/sandbox) and [settings reference](https://antigravity.google/docs/cli/settings). See the [Antigravity CLI permissions docs](https://antigravity.google/docs/cli-permissions).\n\nFor Rovo Dev CLI, this generates the `toolPermissions` block of `config.yml` — the global `~/.rovodev/config.yml`, and in project mode the repo-committed `.rovodev/config.yml` that the [Bitbucket Cloud Agentic Pipelines guide](https://support.atlassian.com/bitbucket-cloud/docs/rovo-dev-advanced-agentic-configuration/) documents (referenced from `bitbucket-pipelines.yml` via `config.path`, or the `--config-file` CLI flag); the project file is deliberately **not** gitignored, since committing it is how Rovo Dev permissions get enforced in CI. Rovo Dev\'s three levels (`allow`/`ask`/`deny`) are an exact 1:1 with rulesync\'s canonical actions, so action values pass through verbatim. The `bash` category maps the catch-all `*` pattern to `bash.default` and every other pattern to a `bash.commands[]` entry `{ command: , permission }` (Rovo Dev matches commands as regexes, so author `bash` patterns accordingly). The `read` category maps to the inspection tools (`open_files`, `expand_code_chunks`, `expand_folder`, `grep`) and `edit`/`write` to the mutation tools (`find_and_replace_code`, `create_file`, `delete_file`, `move_file`), written under **`toolPermissions.tools`** — the depth Rovo Dev documents. (Earlier Rulesync versions wrote them one level up, directly under `toolPermissions`, where Rovo Dev ignores them; import still reads that legacy shape as a fallback for keys the nested block says nothing about, so an old file is not lost, and a regenerate deletes the stale copies.) Because these per-tool keys hold a single level (no per-pattern rules), only the catch-all `*` of each category sets the level. Rovo Dev rewrites a single tool key when the user answers "always allow" to one prompt, so the four keys of a category can disagree; import collapses them back onto one catch-all by taking the strictest level (`deny` > `ask` > `allow`) rather than whichever key is read last. Rovo Dev\'s planning and Atlassian tools split the same way, so they ride the same two categories rather than getting one of their own: `read` also reaches `getJiraIssue` and `getConfluencePage`, and `edit`/`write` also reach `createJiraIssue`, `updateJiraIssue`, `createConfluencePage`, `updateConfluencePage` and `createTechnicalPlan` (grouped with the mutating tools because it is the planning tool that produces an artifact rather than reading one). Bear that in mind when authoring: an `edit: deny` reaches Jira and Confluence, not just the working tree. Because `edit` and `write` both map onto the same mutation tools, a conflicting catch-all between them cannot be represented; the stricter of the two levels is kept — the same `deny` > `ask` > `allow` rule import uses — and a warning is logged. Non-catch-all `allow` paths in those categories are surfaced as `allowedExternalPaths` so explicit grants are not dropped; non-`allow` non-catch-all rules cannot be expressed per-path and are skipped with a warning. Categories without a clean Rovo Dev target (e.g. `webfetch`) are skipped with a warning. `config.yml` holds all of Rovo Dev\'s settings (`agent`, `sessions`, `mcp`, etc.), so the `toolPermissions` block is merged in place — every other top-level key is preserved, as is any key inside `toolPermissions` that Rulesync does not manage — including tools inside `toolPermissions.tools` that no canonical category maps to. On **import**, a tool key the file is silent about counts as the implicit fallback level (`toolPermissions.default`, or Rovo Dev\'s own `ask`) rather than as absent, and the category still collapses to the strictest of the set. That matters because Rovo Dev writes a single key when the user answers "always allow" to one prompt: without the fallback, one such answer about `create_file` would import as a blanket `edit: allow`, and the next generate would hand that grant to every other tool of the category — Jira and Confluence writes included. A category the file says nothing about at all is still skipped rather than invented.\n\n**Migration note.** `toolPermissions.default` and the seven planning/Atlassian keys became Rulesync-owned in the release that added them. Ownership means the first generate after upgrading removes a hand-written value for one of them unless `.rulesync/permissions.*` produces it — a hand-written `tools.createJiraIssue: deny` or `default: deny` with no matching rule in the rulesync source is dropped (with a warning naming each key), falling back to Rovo Dev\'s `ask`. Run `rulesync import --targets rovodev --features permissions` before the first generate to carry those values into the rulesync source.\n\nThe canonical all-tools category `*` maps to `toolPermissions.default`, the level Rovo Dev falls back to for any tool with no more specific setting (Rovo Dev\'s own default is `ask`) — derived from its catch-all exactly as `bash.default` is derived from `bash`\'s, and round-tripped back on import. The default is a single level, so a pattern rule inside the `*` category has no counterpart and is skipped with a warning. The keys Rulesync does manage (`default`, `bash`, `allowedExternalPaths`, and the per-tool keys above) are owned rather than merged: each generate rewrites them from `.rulesync/permissions.*`, so removing a rule there removes it from `config.yml` too (a source stating no rule at all clears them; one whose rules simply have no Rovo Dev counterpart keeps the block\'s restrictions but strips its grants — an `allow` there is normally a leftover of an earlier generate, and dropping one falls back to Rovo Dev\'s stricter default, whereas clearing the whole block would relax every level), logging a warning naming each owned key it removes — per-tool levels and `allowedExternalPaths` are written from inside a Rovo Dev session too, by an "always allow" prompt answer and the `/directories` command, and a hand-edit to one of those keys — including a path added with the in-session `/directories` command, which writes to `allowedExternalPaths` — is replaced on the next generate (values only — YAML comments and formatting in the existing file are not retained on rewrite) — and the file is never deleted. See the [Rovo Dev CLI settings](https://support.atlassian.com/rovo/docs/manage-rovo-dev-cli-settings/) and [tool permissions](https://support.atlassian.com/rovo/docs/use-tools-in-rovo-dev-cli/) docs.\n\nFor Goose, this generates the `user` block of the global `~/.config/goose/permission.yaml` (**global mode only** — Goose persists per-tool permission overrides only under the home directory and has no project-scoped permissions file). Goose stores permissions as a YAML map of mode key → `{ always_allow, ask_before, never_allow }`, where each field is a list of tool-name strings; rulesync writes the user-set decisions under the `user` key. Action mapping is a 1:1: `allow` → `always_allow`, `ask` → `ask_before`, `deny` → `never_allow`. Tool-name mapping: `bash` → `developer__shell`, `edit` → `developer__text_editor`; every other category passes through verbatim as the Goose tool name (so namespaced tools like `developer__text_editor` or `developer__image_processor` round-trip). Because Goose permission lists hold **whole tool names** rather than per-command/per-path globs, only a category\'s catch-all `*` pattern is representable — non-catch-all patterns are skipped with a warning. `write` collapses onto `developer__text_editor` too, so a conflicting `edit`/`write` catch-all cannot be represented; `edit` takes precedence and a warning is logged. The `permission.yaml` file is merged in place: the `user` block is owned by rulesync, while every other top-level key (notably the `smart_approve` LLM-decision cache) is preserved, and the file is never deleted. See the [Goose tool permissions docs](https://goose-docs.ai/docs/guides/managing-tools/tool-permissions/).\n\nFor the Grok Build CLI (`grokcli`), this generates Grok\'s Claude-style `[permission]` rule arrays — `allow` / `deny` / `ask` — in the project `./.grok/config.toml` (project mode) or the user `~/.grok/config.toml` (global mode, via `--global`). Grok documents that "Project configs are limited to MCP servers, plugins, and permission rules, not full user configs" ([settings docs](https://docs.x.ai/build/settings)), so the fine-grained `[permission]` rules are valid at both scopes. Each canonical `permission..` becomes a Grok entry bucketed into the matching array: `bash`→`Bash`, `read`→`Read`, `edit`→`Edit`, `grep`→`Grep`, `webfetch`→`WebFetch`, and `mcp____`→`MCPTool(__)`; a `*` pattern emits the bare tool name (e.g. `Bash`) and a concrete pattern emits `Tool(pattern)` (e.g. `Bash(git *)`). `write` collapses onto `Edit` (Grok has no separate `Write` tool — a documented lossy mapping), and categories with no Grok tool (`websearch`, `glob`, `notebookedit`, `agent`) are skipped, with a warning when a skipped category carries a `deny` rule. Grok evaluates the arrays with precedence `deny > ask > allow`, which import mirrors (a tool listed in multiple arrays resolves to the strictest action). The coarse `[ui] permission_mode` toggle (`"ask"` / `"always-approve"`) is still written as a backward-compatible fallback for older Grok versions: `always-approve` when the config is pure-`allow`, otherwise `ask` (conservative — never `always-approve` while any `deny`/`ask` rule exists, so it never contradicts the fine-grained arrays). On import, the `[permission]` arrays are parsed back into canonical categories when present; only when no `[permission]` section exists do we fall back to the coarse mode (`always-approve` ⇄ `bash: { "*": "allow" }`, `ask`/unset ⇄ `bash: { "*": "ask" }`). `config.toml` is shared with the MCP feature, so rulesync owns the `[permission]` `allow`/`deny`/`ask` arrays and `[ui] permission_mode` while every other key (e.g. `[mcp_servers]`, verbose `[permission] rules`, `[sandbox]`) is preserved, and the file is never deleted. See the [Grok CLI settings reference](https://docs.x.ai/build/settings/reference) and [modes docs](https://docs.x.ai/build/modes-and-commands).\n\nFor Vibe (mistral-vibe), this generates per-tool `[tools.]` tables in the shared `.vibe/config.toml` (project mode) or `~/.vibe/config.toml` (global mode). Tool-name mapping: `bash` → `bash`, `read` → `read_file`, `edit` → `edit`, `write` → `write_file`, `webfetch` → `web_fetch`, `websearch` → `web_search`, `grep` → `grep`, `agent` → `task`. These are Vibe\'s builtin tool names (`BaseTool.get_name()`, the snake_case of each tool class); `edit` and `write_file` are distinct tools — `write_file` has been create-only since v2.14.0 — so the two canonical categories no longer collapse onto one name. **Migration:** a `config.toml` written by an earlier Rulesync may still carry `write_file` entries derived from the `edit` category, or inert `[tools.fetch]` / `[tools.search_web]` / `[tools.agent]` blocks. Rulesync only rewrites the names it now emits, so remove those stale entries by hand — a leftover `disabled_tools = ["write_file"]` keeps Vibe\'s `write_file` disabled even though no canonical rule asks for it, and inert `[tools.glob]` / `[tools.notebookedit]` tables an earlier Rulesync emitted for tools Vibe does not have stay on disk until removed by hand (new generates skip those categories instead of rewriting them). Within a category, the catch-all `*` pattern sets the per-tool `permission` (`allow` → `always`, `ask` → `ask`, `deny` → `never`); a wildcard deny additionally adds the tool to the top-level `disabled_tools` filter. A wildcard allow deliberately does **not** touch the top-level `enabled_tools` key: upstream treats it as an **exclusive** allowlist (“if set, only these tools will be active”), so expressing allows through it — as earlier Rulesync versions did — silently switched off every other builtin and MCP tool; the per-tool `permission = "always"` entry carries the allow completely, and a regenerate now removes the exclusive entries an earlier version wrote for the tools it configures; specific patterns become **`allowlist` / `denylist`** entries — these are the keys Vibe\'s permission engine actually reads (`BaseToolConfig`), so the legacy `allow` / `deny` keys are dropped on generate (still honored as a fallback on import). Vibe has no per-pattern `ask`, so pattern-level `ask` rules are skipped with a warning. A canonical category with no Vibe builtin tool at all (e.g. `glob`, `notebookedit`) is likewise skipped with a warning instead of emitting an inert `[tools.]` table — a `deny` written there would look applied while Vibe ignores it. Unknown `[tools.*]` tables already on disk still round-trip untouched. The `config.toml` file is shared with the MCP feature, so writes merge non-destructively and the file is never deleted. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/tools/base.py`).\n\n> **Vibe-only override (`vibe` key):** Vibe\'s `BaseToolConfig` also carries a `sensitive_patterns` list — patterns that escalate to **ASK even when the base permission is ALWAYS** (allow). The canonical model can only set a pattern to a single `allow`/`ask`/`deny`, so an "allow by default but ask on these patterns" escalation cannot be expressed in the shared block. Add a tool-scoped `vibe` override to author it: `vibe.permission..sensitive_patterns` carries the list per canonical category (e.g. `bash`, `edit`), while the shared `permission` block still sets the base permission and allow/deny lists. On import, a tool\'s `sensitive_patterns` round-trips back into the `vibe` override (the base allow stays in the shared block). rulesync owns the list for any category named in the override (a present list is set, an empty one clears it); categories not named keep whatever the existing `config.toml` had. The override also carries `vibe.enabled_tools` — the only way to author Vibe\'s top-level **exclusive** allowlist. The list is written verbatim in Vibe\'s tool-name vocabulary (declaring it, even empty, makes rulesync own the whole key), and on import a non-empty `enabled_tools` is lifted back into the override rather than being misread as a set of `"*": "allow"` grants. Note the `config.toml` scope semantics: Vibe reads exactly **one** config file — the trusted project `.vibe/config.toml` when present, otherwise `~/.vibe/config.toml` (a fallback, not a merge; single code path since v2.22.0) — so a `--global` run warns when the current project has its own `config.toml`, which shadows the global one for the `mcp` and `permissions` surfaces (rules, hooks, agents and skills genuinely combine scopes).\n>\n> ```json\n> {\n> "permission": { "bash": { "*": "allow" } },\n> "vibe": { "permission": { "bash": { "sensitive_patterns": ["rm *", "sudo *"] } } }\n> }\n> ```\n\nFor Takt, this generates the `default_permission_mode` under `provider_profiles.` in the shared `.takt/config.yaml` (project mode) or `~/.takt/config.yaml` (global mode). Takt does not have per-tool / per-pattern rules; tool gating is a single coarse mode per provider profile, ordered `readonly` < `edit` < `full` (`readonly` may only read, `edit` may also edit/write files, `full` may also run shell commands). The active provider is named by the top-level `provider:` key (defaulting to `claude`). The mapping is therefore **lossy**: on generate, a single mode is derived with this precedence — (1) any `deny` rule anywhere ⇒ `readonly` (conservative — keep the narrowest mode whenever the user expressed any restriction); (2) else any `edit`/`write` category `allow` rule ⇒ `edit`; (3) else any `bash` category `allow` rule ⇒ `full`; (4) else ⇒ `readonly` (safe default). On import, `full` ⇄ `bash: { "*": "allow" }`, `edit` ⇄ `edit: { "*": "allow" }`, and `readonly` (or an unset/unknown mode) ⇄ `bash: { "*": "deny" }`. `config.yaml` is shared with other Takt settings, so the mode is merged in place — every other provider profile and all other top-level keys are preserved — and the file is never deleted. Takt\'s default-deny **workflow security policies** — `workflow_arpeggio` (`custom_data_source_modules`, `custom_merge_inline_js`, `custom_merge_files`), `workflow_runtime_prepare.custom_scripts`, `workflow_command_gates.custom_scripts`, `sync_conflict_resolver.auto_approve_tools`, and the `allow_git_hooks` / `allow_git_filters` booleans — have no canonical permission category, so they are authored through the `takt` override block of `.rulesync/permissions.*` and round-trip on import. Each admits one class of user-supplied code, so only the exact shapes Takt itself accepts are written: a sub-key Takt does not declare is dropped with a warning rather than passed through, since Takt\'s schemas are strict and reject the whole file on an unknown key, while a value of the wrong type fails when `.rulesync/permissions.*` is read. Removing one of these keys from `config.yaml` because the source no longer states it is warned about too — including a key put there by hand, which owning them implies. Deleting `.rulesync/permissions.*` altogether is different: the feature has no source to generate from, so nothing runs and whatever is in `config.yaml` stays. These keys are also authoritative rather than merged — revoking one in `.rulesync/permissions.*` removes it from `config.yaml`, instead of leaving the capability switched on. `workflow_mcp_servers` stays with the MCP feature, which derives it from the transports in use.\n\nTwo Takt-specific surfaces with no canonical category can be authored (and round-trip) through an optional `takt` override block in `.rulesync/permissions.jsonc`: `step_permission_overrides` (a per-workflow-step map `` ⇒ `readonly`/`edit`/`full`, written inside the active provider profile and layered by Takt on top of `default_permission_mode`) and `provider_options` (a top-level, per-provider table of sandbox/network knobs orthogonal to the mode, e.g. `codex.network_access`, `claude.sandbox.allow_unsandboxed_commands`, `opencode.allowed_tools`). Example: `{ "permission": { … }, "takt": { "step_permission_overrides": { "ai_review": "readonly" }, "provider_options": { "codex": { "network_access": true } } } }`. Note the workflow-step `required_permission_mode` floor is a field of the **workflow YAML**, not `config.yaml`, so it is intentionally out of scope (Takt\'s config loader hard-rejects unknown top-level keys). See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\nFor Amp, this writes to the shared `.amp/settings.json` (project mode) or `~/.config/amp/settings.json` (global mode), using **two** permission surfaces. In rulesync\'s canonical model the category name **is** the Amp tool name. A **whole-tool deny** (pattern `*`) is written to the bare `amp.tools.disable` array (the tool name is pushed verbatim, preserving `builtin:` prefixes and the `*` glob) for backwards compatibility. Every **lossy** case is written to the ordered `amp.permissions` array instead of being dropped: an **argument-specific deny** (pattern `!== "*"`) becomes `{ tool, action: "reject", matches: { cmd: } }`, and every `allow` / `ask` rule becomes `{ tool, action, matches?: { cmd } }` (the `matches` object is omitted for the `*` catch-all). Amp evaluates `amp.permissions` **first-match-wins**, so generated entries are ordered deterministically and fail-closed: sorted by tool name, then entries **with** `matches.cmd` (more specific) before catch-alls, then by action priority **`reject` < `ask` < `allow`**, then by `cmd`. `amp.permissions` is Amp\'s documented **legacy / backwards-compatibility** surface — it remains functional and is the only place to express `allow`/`ask` and argument-specific `reject` rules. **Ownership:** rulesync OWNS and wholesale-replaces the `allow`/`ask`/`reject` entries on every generate, but **preserves any existing `action: "delegate"` entry** (rulesync\'s canonical model has no `delegate` equivalent); preserved `delegate` entries are placed **after** the rulesync-generated entries (so the regenerated rules take precedence under first-match-wins). On **import**, both keys are read and merged into one canonical config: `amp.tools.disable[tool]` → `{ tool: { "*": "deny" } }`, and each `amp.permissions` entry → `{ tool: { (matches?.cmd ?? "*"): mapped } }` (`reject` → `deny`, `allow` → `allow`, `ask` → `ask`; `delegate` is skipped). When both sources target the same tool+pattern, the **most restrictive action wins** (`deny` > `ask` > `allow`). The settings file is shared with the MCP feature (`amp.mcpServers`), so all other keys are preserved on round-trip and the file is never deleted. Tool names and `cmd` patterns that are prototype-pollution keys (`__proto__`, `constructor`, `prototype`) are skipped defensively.\n\nAmp shapes with no canonical category are authored (and round-trip) through an optional `amp` override block in `.rulesync/permissions.jsonc`: `permissions` — extra `amp.permissions` entries with non-`cmd` matchers (`path`/`url`/`query`/…), regex/array match values, `context` (`thread`/`subagent`), `delegate` (+`to`), or `reject` (+`message`), appended **after** the canonical-generated entries (so generated allow/ask/reject rules take precedence under first-match-wins, with authored entries as later fallbacks); `mcpPermissions` — Amp\'s `amp.mcpPermissions` array; `guardedFiles` — `amp.guardedFiles.allowlist` (globs allowed without confirmation); and `dangerouslyAllowAll` — `amp.dangerouslyAllowAll`. When the override authors `permissions` it becomes the source of truth for the extra entries; otherwise any hand-authored `delegate` entry in the existing file is preserved. On import, `amp.permissions` entries that are **not** canonical-expressible (non-`cmd` matcher, `delegate`, `reject`+`message`, `context`) are lifted verbatim into `amp.permissions` of the override rather than dropped. Example: `{ "permission": { … }, "amp": { "dangerouslyAllowAll": false, "guardedFiles": { "allowlist": ["docs/**"] }, "permissions": [{ "tool": "Bash", "action": "delegate", "to": "approve.sh" }] } }`. See the [Amp manual](https://ampcode.com/manual).\n\nFor JetBrains Junie CLI, this generates the Action Allowlist `rules` object in `~/.junie/allowlist.json` (**global mode only** — Junie CLI resolves exactly one allowlist path under its home directory and never reads a project-scope `.junie/allowlist.json`; verified against release `2383.10`). Junie evaluates the allowlist top-to-bottom (first match wins) and groups rules into buckets, onto which rulesync categories map: `bash` → `executables`, `edit`/`write` → `fileEditing`, `read` → `readOutsideProject`, `mcp` → `mcpTools`. Every rule group is written as Junie\'s `AllowListRuleSet` **object** — `{ "default"?: "allow"|"ask", "rules": [ … ] }` — never a bare array: Junie\'s parser rejects the array form for the **whole file** and then discards and overwrites `allowlist.json`, so the shape matters. Earlier rulesync versions emitted the array form; it is still tolerated on import, but only the object form is generated. Each rule carries an `action` plus either a literal `prefix` (matches commands that start with it) or a glob `pattern` (`*`, `**`, `?`, `[abc]`, `[!abc]`); rulesync emits `pattern` when the canonical pattern contains a glob metacharacter (`*`, `?`, `[`) and `prefix` otherwise. Junie accepts only `allow` and `ask` as actions — there is **no `deny`** (a `deny` fails the whole-file parse) — so a canonical `deny` is downgraded to the nearest valid action, `ask` (which still withholds auto-approval), with a warning (`allow`/`ask` map 1:1). Categories Junie cannot represent (e.g. `webfetch`, `websearch`) are skipped with a warning when they carry rules. rulesync **owns each mapped group\'s rule list** (replaced on each generate), while a per-group `default` and the whole `readSecretFile` group — which restricts what Junie may read — are preserved from the existing file when not authored via the `junie` override below. Because `edit`/`write` both collapse onto `fileEditing`, importing normalizes back to `edit` (a documented, lossy mapping). The `allowlist.json` file is never deleted. See the [Junie Action Allowlist docs](https://junie.jetbrains.com/docs/action-allowlist-junie-cli.html).\n\n> **Junie-only override (`junie` key):** Junie\'s `allowlist.json` has settings with no canonical per-glob slot — the top-level autonomy knobs `allowReadonlyCommands` (a boolean auto-allowing read-only commands) and `defaultBehavior` (the fallback action when no rule matches; an `allow`/`ask` enum — Junie\'s `AllowListDecision` accepts nothing else, and an invalid value fails the whole-file parse), plus two group-shaped settings: `readSecretFile` (the fifth rule group, restricting reads of secret files — canonical `read` is already taken by `readOutsideProject`, so this group is authored whole as `{ "default"?, "rules": [ … ] }`) and `ruleDefaults` (each mapped group\'s own fallback action, e.g. `{ "executables": "ask" }`). Add a tool-scoped `junie` override to author them: the scalar knobs are merged onto the top level of `allowlist.json` (the override wins) while the shared `permission` block keeps driving the mapped groups\' rule lists, and the group-shaped settings land inside the `rules` object. On **import**, all of these are lifted from `allowlist.json` into the `junie` override, so they are authorable and portable instead of only round-trip-preserved. Any other unmodeled top-level key is preserved verbatim. Example:\n>\n> ```json\n> {\n> "permission": { "bash": { "git ": "allow" } },\n> "junie": {\n> "allowReadonlyCommands": true,\n> "defaultBehavior": "ask",\n> "ruleDefaults": { "executables": "ask" },\n> "readSecretFile": { "rules": [{ "pattern": "**/.env", "action": "ask" }] }\n> }\n> }\n> ```\n\nFor Reasonix, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the `[permissions]` table of the shared `reasonix.toml` (project mode) or `~/.reasonix/config.toml` (global mode) — the same TOML file the MCP feature\'s `[[plugins]]` array-of-tables lives in. The rule syntax mirrors Claude Code\'s: entries are `Bash()`, `Read()`, `Edit()`, `Write()`, `WebFetch()`, `WebSearch()`, `Grep()`, `Glob()`, `NotebookEdit()`, `Agent()`, etc. (Reasonix\'s SPEC.md documents these as "Claude Code-style" families; `agent` → `Agent` is the one lower-confidence mapping, since Reasonix\'s own delegation tool is internally named `task`). `[permissions].mode` (the writer fallback: `ask`/`allow`/`deny`) has no canonical rulesync equivalent and is preserved untouched. The TOML file is shared with the MCP feature, so writes only replace the `permissions` table — every other table (`[[plugins]]`, `[agent]`, `[ui]`, …) is preserved on round-trip, and the file is never deleted. See [SPEC.md §3.7 Permissions](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md).\n\n> **Reasonix-only override (`reasonix` key):** Reasonix has security axes orthogonal to per-tool allow/ask/deny with no canonical category — the `[sandbox]` enforcement table (`workspace_root`, `allow_write`, `forbid_read`, `bash` = `enforce`/`off`, `network`) and the plan-mode read-only command list under `[agent]` (`plan_mode_read_only_commands`, which upstream keeps for legacy compatibility only — Plan bash goes through Permissions now). Its sibling `plan_mode_allowed_tools` left the documented config surface in v1.17.18: an existing value is still lifted out of `[agent]` on import, so it does not vanish from an imported config, but whenever the override writes `[agent]` the key is removed from the file with a warning — including a value already there, since leaving that one alone would mean narrowing the list is the one edit that never lands. Add a tool-scoped `reasonix` override to author them: `reasonix.sandbox` and `reasonix.agent` are shallow-merged into the matching `reasonix.toml` table at its top level (override keys win, unrelated sibling keys such as `[agent].model` are preserved), while the shared `permission` block keeps driving `[permissions].allow`/`ask`/`deny`. The override also carries `rawAllow`/`rawAsk`/`rawDeny` — verbatim `[permissions]` entries merged into the generated arrays untranslated. They exist for the first-class `Bash=` exact-command form (SPEC §3.7, v1.18.0: metacharacters in the literal are ordinary characters and only the identical complete command matches), which the canonical tool→pattern→action shape cannot express and which is the only way to pre-authorize dynamic or nested Bash in headless `reasonix run` short of YOLO. Exact entries already in `reasonix.toml` — Reasonix writes them itself as remembered approvals — are always preserved on generate, even for tools the shared block manages. On import, the whole `[sandbox]` table round-trips (it is a dedicated security surface), only the plan-mode keys are lifted from `[agent]`, and exact `Tool=` entries are lifted into `rawAllow`/`rawAsk`/`rawDeny` instead of masquerading as a bogus tool category in the shared block.\n>\n> ```json\n> {\n> "permission": { "bash": { "git status*": "allow" } },\n> "reasonix": {\n> "sandbox": { "bash": "enforce", "network": false },\n> "agent": { "plan_mode_read_only_commands": ["gh pr diff"] }\n> }\n> }\n> ```\n>\n> The retired `[[plugins]].trusted_read_only_tools` MCP read-only trust list is per-plugin (an array-of-tables shared with the MCP feature) and is not covered by this override.\n\n> **Note: Interaction with deprecated ignore feature.** Both the ignore feature and the permissions feature can manage `Read` tool deny entries in `.claude/settings.json`. When both features configure the `Read` tool, the **permissions feature takes precedence** and a warning is emitted. Migrate the ignore patterns to `read` deny rules in `.rulesync/permissions.jsonc`, then remove `ignore` from the project features and delete the obsolete ignore source.\n', + '# File Formats\n\n## Symlinks\n\nRulesync follows symbolic links when it discovers source files, whether you use a plain `.rulesync/` directory or a separate `--input-root`. Glob-based discovery (rules, commands, subagents, skills) follows symlinked files and directories; single fixed-path files such as `.rulesyncignore`, `.rulesync/mcp.jsonc`, and `.rulesync/permissions.jsonc` are likewise resolved transparently by the OS when read. A symlink inside the input tree that points elsewhere is followed transparently, and the resolved file content is copied into the generated output. This is intentional: it lets you centralize shared skills or rules in one place and reference them via symlinks without duplication (see [issue #1707](https://github.com/dyoshikawa/rulesync/issues/1707)).\n\nThe trust boundary is the directory you point Rulesync at. There is **no** `realpath`-based containment check on individual symlinks, so a link may resolve to a target outside the input root — enforcing containment would break the shared-file use case above. Only run Rulesync against trees you control. Directory symlink **cycles** are handled safely: results are deduplicated by real path, so a cycle does not produce duplicated output. Note that the remote-fetch path (`rulesync fetch` from a Git repository) is a separate, hardened code path that **skips** symlinks entirely, so untrusted remote content never has its symlinks followed.\n\nOne discovery pass is deliberately excluded from the follow-symlinks rule: the scan for nested `AGENTS.md` files (see the `agentsmd` note below). Unlike every other glob above, it walks the whole project rather than a rulesync-owned directory, so a symlink committed to a repository you cloned could otherwise pull a file from outside the project into version-controlled `.rulesync/`. That scan does not follow symlinks.\n\n## `rulesync/rules/*.md`\n\nExample:\n\n```md\n---\nroot: true # true for root-level rules, false for details such as `.agents/memories/*.md`\nlocalRoot: false # (optional, default: false) true for project-specific local rules. Claude Code: CLAUDE.local.md; Rovodev (Rovo Dev CLI) and Roo Code: AGENTS.local.md; Qwen Code: .qwen/QWEN.local.md; Others: append to root file. See the localRoot note below for import behavior\ntargets: ["*"] # * = all, or specific tools\ndescription: "Rulesync project overview and development guidelines for unified AI rules management CLI tool"\nglobs: ["**/*"] # file patterns to match (e.g., ["*.md", "*.txt"])\nagentsmd: # agentsmd and codexcli specific parameters\n # Support for using nested AGENTS.md files for subprojects in a large monorepo.\n # This option is available only if root is false.\n # If subprojectPath is provided, the file is located in `${subprojectPath}/AGENTS.md`.\n # If subprojectPath is not provided and root is false, the file is located in `.agents/memories/*.md`.\n subprojectPath: "path/to/subproject"\ncursor: # cursor specific parameters\n alwaysApply: true\n description: "Rulesync project overview and development guidelines for unified AI rules management CLI tool"\n globs: ["*"]\ncopilot: # copilot specific parameters (non-root `*.instructions.md` files only)\n name: "TypeScript Style" # (optional) display name shown in the VS Code UI; defaults to the file name\n excludeAgent: "code-review" # (optional) "code-review" or "cloud-agent": skip this file for that agent\nantigravity: # antigravity specific parameters\n trigger: "always_on" # always_on, glob, manual, or model_decision\n globs: ["**/*"] # (optional) file patterns to match when trigger is "glob"\n description: "When to apply this rule" # (optional) used with "model_decision" trigger\ndevin: # devin (Devin Desktop, formerly Windsurf) specific parameters\n trigger: "always_on" # always_on, glob, manual, or model_decision\n globs: ["**/*"] # (optional) file patterns to match when trigger is "glob"\n description: "When to apply this rule" # (optional) used with "model_decision" trigger\naugmentcode: # augmentcode specific parameters\n type: "always_apply" # always_apply, manual, or agent_requested\n description: "When to apply this rule" # (optional) used with "agent_requested" type\nkiro: # kiro specific parameters (steering inclusion)\n inclusion: "fileMatch" # always, fileMatch, manual, or auto\n fileMatchPattern: ["src/components/**/*.tsx"] # (optional) glob string or array of globs, used when inclusion is "fileMatch"\n name: "api-design" # (optional) required when inclusion is "auto"; the steering entry key\n description: "REST API design patterns. Use when creating or modifying API endpoints." # (optional) required when inclusion is "auto"; Kiro auto-includes the file when a request matches this\ntakt: # takt specific parameters (optional; emitted under .takt/facets/policies/ — frontmatter is dropped on emit)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\n extends: "base" # (optional) emit a leading `{extends:}` facet-inheritance directive (Takt 0.39.0+)\n facet: "output-contracts" # (optional) "policies" (default) or "output-contracts": redirect this rule to Takt\'s output-structure/report-template facet\n---\n\n# Rulesync Project Overview\n\nThis is Rulesync, a Node.js CLI tool that automatically generates configuration files for various AI development tools from unified AI rule files. The project enables teams to maintain consistent AI coding assistant rules across multiple tools.\n\n...\n```\n\nMultiple files can set `root: true` for the same target in project and global modes. Rulesync renders each file through the target adapter, then combines compatible root or plain-Markdown single-file outputs in deterministic source-discovery order with one blank line between fragments. Local rules are ordered lexicographically by source file path and composed before non-overridden `.curated/` rules, which are also ordered lexicographically; filename prefixes such as `10-` and `20-` control composition order within each set. Targets that map source rules to distinct native paths keep those files separate. Explicitly supported plain-Markdown modular rules that normalize to the same output path are combined; a fragment whose generated output carries its own frontmatter block (such as Amp\'s `globs:` gate) is never composed and stays a separate file instead. Unsafe collisions involving a source `root: true` rule fail. Other exact or case-insensitive modular collisions remain separate and produce a warning that the last write wins wherever the filesystem treats their paths as the same.\n\n> **localRoot import note:** For the tools that emit a separate personal local file (Claude Code and its legacy layout: `CLAUDE.local.md`; Rovodev and Roo Code: `AGENTS.local.md`; Qwen Code: `.qwen/QWEN.local.md`), `rulesync import` also reads that file back as a `localRoot: true` rule under `.rulesync/rules/`, keeping the tool-side basename. The imported rule\'s `targets` is scoped to the tool it was imported from, not `"*"` — a wildcard would spread the personal content into other tools\' committed root files on the next generate (tools without a separate local file append `localRoot` bodies to their root file), and importing from several tools would otherwise produce conflicting wildcard `localRoot` rules. Widen `targets` by hand if you do want the content shared. The same scoping applies to `rulesync convert`: converting to a different tool drops the source tool\'s personal local file rather than folding it into the destination\'s root file. The derived `.gitignore` covers the imported copy via `.rulesync/rules/*.local.md`; run `rulesync gitignore` after a first import if the project\'s `.gitignore` has not been generated yet, so the personal content stays untracked. Project scope only, like `localRoot` generation itself.\n\n> **AGENTS.md standard note (`agentsmd`):** Nested `AGENTS.md` files are the standard\'s only scoping mechanism — agents read the nearest file in the directory tree, so the closest one wins. Rulesync writes them from `agentsmd.subprojectPath` and, on **import**, discovers them by scanning the project for `**/AGENTS.md`. Hidden directories (other tools\' generated output, including rulesync\'s own) are skipped at any depth, as are `node_modules/` and `__pycache__/`. Build, vendoring and scratch directories (`vendor/`, `third_party/`, `dist/`, `build/`, `out/`, `target/`, `coverage/`, `tmp/`, `temp/`, `venv/`) are skipped **at the project root only**, because a top-level `build/` is a build directory while `packages/build/` is a real subproject. Beyond those names, the scan honors your `.gitignore`: a file git does not track is not your project\'s source, and copying a vendored dependency\'s rule file into version-controlled `.rulesync/rules/` would hand third-party instructions to every tool — including the ones that concatenate non-root rules into a single always-loaded file. (Ignore rules come from the `.gitignore` files at and below the output root — a parent repository\'s rules are not consulted, so running against a subdirectory only sees that subdirectory\'s own. The test is applied to the _directories_ above each file, not the file itself, so the `**/AGENTS.md` entry that `rulesync gitignore` writes for its own output does not disable the scan; the flip side is that ignoring one individual `AGENTS.md` no longer keeps it out of the import.) Symbolic links are not followed, so a link committed to a repository cannot pull a file from outside the project into version-controlled `.rulesync/`. The scan is import-only: a nested file rulesync did not write is never removed by `--delete`. That means deleting the rulesync rule stops the reference from being listed in the root `AGENTS.md`, but leaves the subproject file itself on disk — where agents still read it, since the nearest file wins. Remove it by hand. Each discovered file is imported to `.rulesync/rules/.md` (e.g. `packages/api/AGENTS.md` → `packages-api.md`) carrying `agentsmd.subprojectPath`, so the next generate puts it back where it came from. A subproject that would claim the reserved `overview.md` name gets an `-agents` suffix instead, so the root rule is never overwritten; any other pair of sources deriving the same name is reported at import time, since only the last one survives. Import always rewrites `.rulesync/rules/`, so a subproject whose derived name matches a rule file you wrote by hand replaces it — pick distinct names, or keep hand-written rules out of the derived namespace. See .\n\n> **Kiro note:** Kiro reads steering files from `.kiro/steering/*.md` and uses an `inclusion` frontmatter block to decide when each is loaded (`always`, `fileMatch` with a `fileMatchPattern`, `manual`, or `auto` — which auto-includes the file when a request matches its companion `description`, keyed by `name`). Rulesync derives this for non-root steering files: an explicit `kiro.inclusion` block round-trips as-is (carrying `name`/`description` through for `auto`); otherwise specific (non-wildcard) `globs` map to `inclusion: fileMatch` (a single glob is written as a string and multiple as a YAML array, both of which Kiro accepts), so the rule applies only to matching files instead of always; otherwise the file stays always-on and is written without a frontmatter block (Kiro\'s no-frontmatter default). The root overview index is always written plain so Kiro always loads it. In **global** mode (`--global`), steering is written to `~/.kiro/steering/` with the root rule as `~/.kiro/steering/product.md` (Kiro does not read `~/AGENTS.md`, so the project-scope root `AGENTS.md` is not used at the home level), and global MCP is written to `~/.kiro/settings/mcp.json`.\n\n> **Grok CLI note:** Grok Build writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.grok/AGENTS.md` (global, via `--global`), and non-root rules to `.grok/rules/*.md` (project) / `~/.grok/rules/*.md` (global). Grok scans that directory flat and in name order, alongside the AGENTS.md family — earlier Rulesync versions folded every topic rule into the single root file, which matched Grok 0.2.54 but not the current release, so regenerate to split them back out. Non-root files carry no frontmatter. Because this is a directory Grok defines rather than one Rulesync invented, a project may already have hand-written files there: Rulesync owns it from now on, so `--delete` removes anything in it — `~/.grok/rules/` included, in global mode — that `.rulesync/rules/` does not produce. Move those files into `.rulesync/rules/` first.\n\n> **Kilo Code note:** Kilo writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.kilo/rules/*.md`. Because Kilo v7 does not auto-load files under `.kilo/rules/`, Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `kilo.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under `.kilo/rules/` — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> In global mode (`--global`), Kilo\'s own layout is asymmetric: the root rule goes to `~/.config/kilo/AGENTS.md`, while non-root rules go to `~/.kilo/rules/*.md` — the same `.kilo`-relative path the skills adapter uses in both scopes. Global rules need no `instructions` registration, because Kilo auto-discovers every `~/.kilo/rules/*.md` on config load; writing the files is enough, and no global `kilo.jsonc` is touched by the rules feature.\n\n> **Kimi Code note:** Kimi Code reads `.kimi-code/AGENTS.md` at project scope and `~/.kimi-code/AGENTS.md` at user scope. When `KIMI_CODE_HOME` is set, Rulesync follows Kimi and resolves every global Kimi-specific file (`AGENTS.md`, `mcp.json`, `config.toml`, `skills/`, and `agents/`) under that custom data root; the shared `~/.agents/skills/` and `~/.agents/agents/` discovery roots remain under the user\'s real home directory. Because Kimi has no dedicated directory for topic-based instruction files, Rulesync folds every non-root rule body into that single file. See the [Kimi Code agents and instruction-files docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html) and [environment-variable docs](https://moonshotai.github.io/kimi-code/en/configuration/env-vars.html).\n\n> **OpenCode note:** OpenCode writes the root rule to the auto-loaded `AGENTS.md` and non-root rules to `.opencode/memories/*.md`. Because OpenCode auto-loads only the root `AGENTS.md` plus files explicitly listed in the `instructions` array of `opencode.json` (it does not auto-discover a rules directory), Rulesync also registers each generated non-root rule file in the `instructions` array of the shared `opencode.json`/`opencode.jsonc` (the root `AGENTS.md` is auto-loaded and is therefore not registered). The same applies in **global** mode (via `--global`): OpenCode reads `instructions` from the global `~/.config/opencode/opencode.json` too, so global non-root rules are written to `~/.config/opencode/memories/*.md` and registered there (entries relative to the config file\'s directory, e.g. `memories/style.md`) instead of being dropped. This merge is non-destructive: existing keys such as `mcp`, `tools`, and `permission` are preserved. Within the `instructions` list rulesync owns the entries under its managed rules directory (`.opencode/memories/`, or `memories/` in the global config) — that subset is rebuilt from the current generate, so deleting a rule also drops its registration — while entries outside it pass through verbatim; the result is deduped and sorted.\n\n> **Qwen Code note:** Qwen Code writes the root rule to the auto-loaded `QWEN.md` (project) / `~/.qwen/QWEN.md` (global, via `--global`) as plain Markdown, and non-root rules to its path-based context-rule directory `.qwen/rules/` (project) / `~/.qwen/rules/` (global). Each non-root rule is a Markdown file with optional YAML frontmatter: Rulesync maps `globs` ⇄ Qwen\'s `paths` (a picomatch glob array) and `description` ⇄ `description`. A rule **with** specific `paths` is _conditional_ — Qwen lazily injects it only when the model touches a matching file — while a rule **without** `paths` (empty or wildcard `**/*`/`*` globs) is a _baseline_ rule loaded at session start and is written as plain Markdown with no frontmatter block. The `.qwen/rules/` directory supersedes the legacy `.qwen/memories/` import surface, so each rule is emitted to exactly one location; the root `QWEN.md` is unchanged. A `localRoot: true` rule is emitted to `.qwen/QWEN.local.md` (project scope only) — Qwen Code v0.16.2\'s personal project context file, loaded after the shared `QWEN.md` so it can override team instructions; the file is covered by the derived `.gitignore` since Qwen Code does not gitignore it for you. See the [Qwen Code memory/context docs](https://github.com/QwenLM/qwen-code).\n\n> **Cline note:** Cline writes the root rule to the auto-loaded `AGENTS.md` (project) as plain Markdown, and non-root rules to its flat `.clinerules/` directory. Each non-root rule is a Markdown file with optional YAML frontmatter for conditional activation: Rulesync maps `globs` ⇄ Cline\'s `paths` (a glob array; the rule loads only when a matching file is in context) and `description` ⇄ `description`. A rule with **specific** `globs` emits `paths`; a rule with **universal** globs (`**/*` or `*`) emits `alwaysApply: true` (always load); a rule **without** globs is written as plain Markdown with no frontmatter block (always active). In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` (Cline CLI v3.0.15+) as plain Markdown, and non-root rules go to `~/Documents/Cline/Rules/*.md` — the global modular-rules directory both the VS Code extension and the SDK/CLI read — with the same conditional-frontmatter conversion project rules get. See the [Cline rules docs](https://docs.cline.bot/customization/cline-rules).\n\n> **Warp note (rules):** Warp reads project rules from the root `AGENTS.md` (or the back-compat `WARP.md`) and does not scan a modular rules directory, so non-root rule bodies are folded into the single root `./AGENTS.md`. In global mode (via `--global`), the root rule is written to the cross-tool `~/.agents/AGENTS.md` — Warp\'s third rule source alongside project and Warp Drive rules, also used from remote hosts in SSH sessions — with the same folding. Other targets (e.g. Cline) own the same global path; as with the shared project-root `AGENTS.md`, each target regenerates the file per its own semantics. See the [Warp rules docs](https://docs.warp.dev/agent-platform/capabilities/rules/) and [file locations](https://docs.warp.dev/terminal/settings/file-locations/).\n\n> **Pi note:** Pi writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.pi/agent/AGENTS.md` (global, via `--global`) as plain Markdown, and folds non-root rules into that single file (Pi has no modular rules directory). Pi additionally loads two system-prompt instruction files. `.pi/APPEND_SYSTEM.md` (project) / `~/.pi/agent/APPEND_SYSTEM.md` (global) **appends** to the default system prompt, and Rulesync emits it from any rule that opts in via a `pi.systemPrompt: append` frontmatter block — those rule bodies are routed to `APPEND_SYSTEM.md` instead of `AGENTS.md`, multiple opted-in rules concatenate in source order, and the file is managed by generate/import/delete like the root file (note: if you hand-authored `.pi/APPEND_SYSTEM.md` before this feature existed, `generate --delete` for the `pi` target now treats it as a managed path and removes it unless a rule opts in — import it first to convert it into a canonical rule). The opt-in is ignored on the `root: true` rule, which always stays on `AGENTS.md` (routing the root away would leave the context file without a merge target). `.pi/SYSTEM.md` (project) / `~/.pi/agent/SYSTEM.md` (global) **replaces** the default system prompt entirely — which silently disables Pi\'s built-in tool instructions — so Rulesync deliberately never emits it and leaves it to be authored by hand. Example:\n>\n> ```yaml\n> ---\n> targets: ["pi"]\n> description: "House style for the system prompt"\n> pi:\n> systemPrompt: append # routes this rule\'s body to .pi/APPEND_SYSTEM.md / ~/.pi/agent/APPEND_SYSTEM.md\n> ---\n> ```\n>\n> See the [Pi usage docs](https://pi.dev/docs/latest/usage).\n\n> **Devin note:** The root rule is emitted to the project-root `AGENTS.md` — the file [Devin CLI / Devin Local actually reads](https://docs.devin.ai/cli/extensibility/rules) (its rules page does not list `.devin/rules/` among its sources) — as plain markdown, while non-root rules keep going to `.devin/rules/*.md`, the Devin Desktop Cascade directory whose `trigger` activation modes (`always_on`, `glob`, `manual`, `model_decision`) are driven by the `devin` frontmatter block. Global mode is unchanged (`~/.config/devin/AGENTS.md`).\n\n> **Amp note:** Amp gates an @-mentioned guidance file on `globs:` YAML frontmatter — the file is loaded only after Amp has read a file matching one of the globs, and **without** the frontmatter it is always loaded. Rulesync therefore emits each non-root rule\'s `globs` as that frontmatter on the generated `.agents/memories/*.md` file (in addition to the advisory `applyTo` value in the root file\'s TOON table, which Amp does not enforce), and restores it into the canonical `globs` on import. Amp implicitly prefixes each glob with `**/` unless it starts with `./` or `../`, so canonical globs pass through verbatim. See [Globs in AGENTS.md](https://ampcode.com/news/globs-in-AGENTS.md).\n\n> **Junie note:** Junie CLI resolves project guidelines **first-match-wins** — `.junie/AGENTS.md` → root `AGENTS.md` → the legacy `.junie/guidelines.md` / `.junie/guidelines/` — and documents no file-inclusion mechanism, so Rulesync writes the root rule to `.junie/AGENTS.md` (project) / `~/.junie/AGENTS.md` (global, via `--global`) and folds non-root rules into that single file. The legacy `.junie/guidelines.md` is still accepted as an import fallback. Earlier Rulesync versions emitted non-root rules to `.junie/memories/*.md`, which is not a documented Junie read path; those files are no longer generated (stale outputs stay gitignored but are not cleaned up automatically). See the [Junie guidelines docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html).\n\n> **Reasonix note:** Reasonix auto-injects a hierarchical instruction document, reading its vendor-specific `REASONIX.md` (alongside the cross-tool `AGENTS.md`/`CLAUDE.md`) by walking user-home → ancestors → project root/local. Rulesync writes the vendor `REASONIX.md` at the project root (project) / `~/.reasonix/REASONIX.md` (global, via `--global`) and folds non-root rules into that single file, since Reasonix has no modular rules directory. Directory-scoped rules are the exception: Context Engine v2 (v1.18.0) also walks from the workspace root to the target path loading per-directory instruction files (“Deeper directories beat broader directories”), so a non-root rule carrying `agentsmd.subprojectPath` is emitted as a nested `/REASONIX.md` (project scope only) instead of being folded — its paragraphs load only under that path rather than being carried on every turn. On **import**, nested `REASONIX.md` files are discovered by the same project scan the AGENTS.md standard uses (same dependency/build-directory exclusions; import-only, never removed by `--delete`) and land in `.rulesync/rules/-reasonix.md` with `targets: ["reasonix"]` and the `subprojectPath` carried, so the next generate puts them back. The `-reasonix` suffix and the reasonix-only targeting keep them from clobbering the AGENTS.md standard\'s derived names or surprising other tools with new nested files; note that a rule targeting both `agentsmd` and `reasonix` with a `subprojectPath` produces a nested `AGENTS.md` **and** a nested `REASONIX.md` in the same directory, both of which Reasonix loads — scope such rules to one target. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md) and [Context Engine v2 docs](https://github.com/esengine/DeepSeek-Reasonix/blob/v1.18.0/docs/SESSION_MEMORY_RETRIEVAL.md).\n\n## `.rulesync/hooks.jsonc`\n\n`.rulesync/hooks.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/hooks.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nHermes Agent accepts native snake-case events under `hermesagent.hooks`: `pre_tool_call`, `post_tool_call`, `transform_terminal_output`, `transform_tool_result`, `transform_llm_output`, `pre_llm_call`, `post_llm_call`, `pre_verify`, `pre_api_request`, `post_api_request`, `api_request_error`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`, `subagent_start`, `subagent_stop`, `pre_gateway_dispatch`, `pre_approval_request`, `post_approval_response`, `kanban_task_claimed`, `kanban_task_completed`, and `kanban_task_blocked`. Rulesync maps shared canonical events first, applies canonical keys from `hermesagent.hooks` next, then applies exact native keys last. An exact native key therefore wins when both forms resolve to the same Hermes event. Native-only events remain under `hermesagent.hooks` on import instead of leaking into other targets.\n\nHooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Qwen Code, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`) — both share one event surface, in which `preToolUse`/`postToolUse` become named `tool.execute.before`/`tool.execute.after` hooks, `preCompact` becomes the named `experimental.session.compacting` hook (which receives `(input, output)` and exposes nothing to match on, so a `matcher` on it is dropped), `beforeShellExecution`/`afterShellExecution` also land in those named `tool.execute.*` hooks with an implicit `input.tool === "bash"` gate — OpenCode has no shell-execution lifecycle event (`command.executed`, which earlier Rulesync versions mapped `afterShellExecution` to, is a _slash-command_ event, so the hook never fired on shell commands; regenerate to fix), and matchers on the shell events are dropped with a warning since the named hooks expose no command text, and the rest are `event.type` dispatches — `sessionStart` → `session.created`, `stop` → `session.idle`, `afterFileEdit` → `file.edited`, `permissionRequest` → `permission.asked`, `postCompact` → `session.compacted`, `afterError` → `session.error`, `fileChanged` → `file.watcher.updated`; Amp hooks are emitted as a TypeScript plugin (`.amp/plugins/rulesync-hooks.ts`, or `~/.config/amp/plugins/rulesync-hooks.ts` in global mode) using `session.start`, `tool.call`, `tool.result`, `agent.start`, and `agent.end`; Pi Coding Agent hooks are emitted as a Rulesync-owned TypeScript extension (`.pi/extensions/rulesync-hooks.ts`, or `~/.pi/agent/extensions/rulesync-hooks.ts` in global mode) that subscribes to Pi\'s snake_case extension events (`sessionStart` → `session_start`, `stop` → `agent_end`, `preToolUse` → `tool_call` with the matcher tested as a regex against the tool name, `preCompact` → `session_before_compact`, `postCompact` → `session_compact`, `postModelInvocation` → `message_end` gated on assistant messages so it runs once per finalized model response) and observes events only — command hooks run but cannot block or mutate Pi events; Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and use `powershell`/`bash` command fields — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli uses a dot-notation (e.g. `session.start`, `tool.error`); Kiro emits hooks into `.kiro/agents/default.json` using Kiro\'s CLI event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI\'s).\n\nExample:\n\n```json\n{\n "version": 1,\n "hooks": {\n "sessionStart": [{ "type": "command", "command": ".rulesync/hooks/session-start.sh" }],\n "preToolUse": [{ "matcher": "Bash", "command": ".rulesync/hooks/confirm.sh" }],\n "postToolUse": [{ "matcher": "Write|Edit", "command": ".rulesync/hooks/format.sh" }],\n "stop": [{ "command": ".rulesync/hooks/audit.sh" }]\n },\n "cursor": {\n "hooks": {\n "afterFileEdit": [{ "command": ".cursor/hooks/format.sh" }]\n }\n },\n "claudecode": {\n "hooks": {\n "notification": [\n {\n "matcher": "permission_prompt",\n "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh"\n }\n ]\n }\n },\n "opencode": {\n "hooks": {\n "afterShellExecution": [{ "command": ".rulesync/hooks/post-shell.sh" }]\n }\n },\n "copilot": {\n "hooks": {\n "afterError": [{ "command": ".rulesync/hooks/report-error.sh" }]\n }\n }\n}\n```\n\n**Top-level keys:**\n\n- `version`: Schema version (currently `1`).\n- `hooks`: Map of canonical event names to an array of hook entries. These are dispatched to every tool that supports the given event.\n- `amp.hooks`, `cursor.hooks`, `claudecode.hooks`, `opencode.hooks`, `kilo.hooks`, `copilot.hooks`, `copilotcli.hooks`, `factorydroid.hooks`, `codexcli.hooks`, `goose.hooks`, `deepagents.hooks`, `kiro.hooks`, `kiro-ide.hooks`, `qwencode.hooks`, `grokcli.hooks`: Tool-specific **override keys**. Entries under these keys are emitted only for the corresponding tool, so tool-only events (e.g. `afterFileEdit` for Cursor/OpenCode/Kilo, `worktreeCreate` for Claude Code, `afterError` for Copilot/Copilot CLI, `PostFileSave`/`PreTaskExec` for Kiro IDE) can coexist with shared ones without leaking to other tools. `copilotcli.hooks` falls back to `copilot.hooks`, which in turn falls back to the shared `hooks` block.\n\n**Hook entry keys:**\n\n- `command` (required): Shell command to execute when the event fires.\n- `type` (optional): One of `"command"` (default), `"prompt"`, `"http"`, `"agent"`, `"mcp_tool"`, or `"function"` — the union of the hook types accepted across supported tools. Each tool supports a subset (most support only `command`); hooks with a type a tool does not support are skipped for that tool with a warning. See notes below.\n- `matcher` (optional): Regex used by tools that scope hooks to specific tool names (e.g. `preToolUse`, `postToolUse`, `notification`). Ignored by events that do not take a matcher (e.g. `sessionStart`, `worktreeCreate`, `worktreeRemove`).\n- `timeout` (optional): Per-hook timeout in seconds, forwarded to tools that support it.\n- `cacheTtl` (optional): Number of seconds to cache a successful hook result. Forwarded to Kiro CLI as `cache_ttl_seconds`; `0` disables caching and Kiro never caches `AgentSpawn` hooks.\n- `failClosed` (optional): Boolean. When `true`, a hook failure (crash, timeout, invalid JSON) blocks the action instead of allowing it through. Passed through to Cursor\'s `.cursor/hooks.json` and to JetBrains Junie\'s `~/.junie/config.json` (as Junie\'s equivalently-named `blockOnError` flag).\n- `async` (optional): Boolean. When `true`, the hook command runs in the background without blocking. Forwarded to Qwen Code (`.qwen/settings.json`) and JetBrains Junie (`~/.junie/config.json`, same field name).\n- `shell` (optional): Either `"bash"` or `"powershell"` — the only two interpreter values any tool accepts. Forwarded to Qwen Code and Claude Code command hooks. Like `args`, `async` and `asyncRewake`, it is documented on command hooks only, so it is not emitted on a hook of another type.\n- `url` / `headers` / `allowedEnvVars` (optional, `http` hooks): the POST target URL, request headers (values support `$VAR` interpolation), and the env-var allowlist for that interpolation. Forwarded to Claude Code and Qwen Code http hooks.\n- `server` / `tool` / `input` (optional, `mcp_tool` hooks): the configured MCP server name, the tool to call on it, and the (arbitrary JSON) arguments, whose string values support `${path}` substitution from the hook input. Forwarded to Claude Code mcp_tool hooks.\n- `model` (optional, `prompt` / `agent` hooks): the model used for evaluation (defaults to a fast model). Forwarded to Claude Code prompt/agent hooks and to Qwen Code prompt hooks.\n- `args` (optional, `command` hooks): an argument list. When present — an empty list counts, and is the form the Claude Code docs use — the tool spawns `command` directly as an executable with these arguments. There is no shell, so Rulesync writes the project-directory prefix as the braced placeholder `${CLAUDE_PROJECT_DIR}/…` that Claude Code substitutes itself, rather than the quoted shell form. Forwarded to Claude Code and AugmentCode. Only `command` is prefixed; entries of `args` are passed through exactly as written.\n- `asyncRewake` (optional): boolean. Like `async`, but wakes Claude when the hook exits with code 2. Forwarded to Claude Code command hooks.\n- `once` (optional): boolean. Run the hook once per session, then remove it. Forwarded to Claude Code (honored in skill frontmatter; accepted but ignored in settings files) and Qwen Code http hooks.\n- `continueOnBlock` (optional): boolean. Feed a blocking hook\'s rejection reason back to the model and continue the turn instead of ending it. Forwarded to Claude Code.\n- `commandWindows` (optional): a Windows-only override for `command`, so one hook set can be cross-platform. Forwarded to Codex CLI command hooks (`.codex/hooks.json`), which is the only tool that accepts it.\n- `statusMessage` (optional): the progress text shown while the hook runs. Forwarded to Qwen Code (command and http hooks) and to Codex CLI command hooks.\n- `if` (optional): a single permission rule (same syntax as `settings.json` permission rules, e.g. `"Bash(rm *)"`) that filters a hook by tool arguments in addition to the tool name. Forwarded to Claude Code, where it is evaluated only on tool events (`preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `permissionDenied`); it round-trips as an opaque string.\n\nTop-level `hooks` keys must be canonical event names; unknown event names are rejected at parse time. Tool-specific override blocks (e.g. `kiro-ide.hooks`) additionally accept tool-native event keys, which pass through verbatim.\n\nEvents present in the shared `hooks` block but unsupported by a given tool are skipped for that tool (a warning is logged at generate time). The canonical `notification` event maps to deepagents-cli\'s `input.required` (human-in-the-loop interrupt).\n\n### Hook event × tool matrix\n\n\n\n| Event | Amp | Claude Code | Claude Code plugin | Codex CLI | GitHub Copilot | GitHub Copilot CLI | Goose | Hermes Agent | Grok CLI | Cursor | deepagents-cli | Factory Droid | OpenCode | Kilo Code | Kimi Code | Vibe Code | Qwen Code | Reasonix | Kiro ⚠️ | Kiro CLI | Kiro IDE | Google Antigravity IDE | Google Antigravity CLI | Google Antigravity plugin | JetBrains Junie | AugmentCode | Devin Desktop | Pi Coding Agent |\n| ---------------------- | :-: | :---------: | :----------------: | :-------: | :------------: | :----------------: | :---: | :----------: | :------: | :----: | :------------: | :-----------: | :------: | :-------: | :-------: | :-------: | :-------: | :------: | :-----: | :------: | :------: | :--------------------: | :--------------------: | :-----------------------: | :-------------: | :---------: | :-----------: | :-------------: |\n| `sessionStart` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ | ✅ | ✅ |\n| `sessionEnd` | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | ✅ | — | ✅ | ✅ | ✅ | ✅ | — | — | — | — | ✅ | ✅ | ✅ | ✅ |\n| `preToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `postToolUse` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ |\n| `preModelInvocation` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | ✅ | ✅ | — | — | — | ✅ |\n| `postModelInvocation` | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | ✅ | ✅ | ✅ | — | — | — | ✅ |\n| `beforeSubmitPrompt` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | — | — | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ | ✅ | ✅ |\n| `stop` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `subagentStop` | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | ✅ | — | — | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — |\n| `preCompact` | — | ✅ | ✅ | ✅ | — | ✅ | — | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ |\n| `postCompact` | — | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | — | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | — | — | — | ✅ | ✅ |\n| `contextOffload` | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `postToolUseFailure` | — | ✅ | ✅ | — | — | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | — | — | ✅ | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `subagentStart` | — | ✅ | ✅ | ✅ | — | ✅ | — | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `beforeShellExecution` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterShellExecution` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `beforeMCPExecution` | — | — | — | — | — | ✅ | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterMCPExecution` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `beforeReadFile` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterFileEdit` | — | — | — | — | — | — | ✅ | — | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterAgentResponse` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterAgentThought` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `beforeTabFileRead` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterTabFileEdit` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `permissionRequest` | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | ✅ | — | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | — | ✅ | — | ✅ | — |\n| `notification` | — | ✅ | ✅ | — | — | ✅ | — | — | ✅ | — | ✅ | ✅ | — | — | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | ✅ | — | — |\n| `setup` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `afterError` | — | — | — | — | ✅ | ✅ | — | — | — | — | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `worktreeCreate` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `worktreeRemove` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `workspaceOpen` | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `messageDisplay` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `todoCreated` | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `todoCompleted` | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `stopFailure` | — | ✅ | ✅ | — | — | — | — | — | ✅ | — | — | — | — | — | ✅ | — | ✅ | — | — | — | — | — | — | — | ✅ | — | — | — |\n| `instructionsLoaded` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `userPromptExpansion` | — | ✅ | ✅ | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `postToolBatch` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `permissionDenied` | — | ✅ | ✅ | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |\n| `taskCreated` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `taskCompleted` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `teammateIdle` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `configChange` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `cwdChanged` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `fileChanged` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `directoryAdded` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `elicitation` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n| `elicitationResult` | — | ✅ | ✅ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |\n\n\n\n> **Note:** `beforeSubmitPrompt`, `stop`, `worktreeCreate`, `worktreeRemove`, `messageDisplay`, `postToolBatch`, `taskCreated`, `taskCompleted`, `teammateIdle`, and `cwdChanged` are the Claude Code events the [matcher table](https://code.claude.com/docs/en/hooks) lists as not supporting the `matcher` field (they fire on every occurrence). A matcher authored on one of them is dropped with a warning rather than written into `settings.json` to be ignored. `directoryAdded` is treated the same way for now: the event is announced in the 2.1.219 changelog but has no row in the docs\' event table yet, so its matcher support is unknown.\n\n> **Note:** Rulesync implements OpenCode hooks as a plugin at `.opencode/plugins/rulesync-hooks.js` and Kilo hooks as a plugin at `.kilo/plugins/rulesync-hooks.js`, so importing from OpenCode/Kilo to rulesync is not supported. Both only support command-type hooks (not prompt-type).\n\n> **Note:** Rulesync implements Amp hooks as a generated TypeScript plugin at `.amp/plugins/rulesync-hooks.ts` (project) or `~/.config/amp/plugins/rulesync-hooks.ts` (global), so importing arbitrary Amp plugin code is not supported. Amp supports command hooks for `sessionStart` → `session.start`, `preToolUse` → `tool.call`, `postToolUse` → `tool.result`, `beforeSubmitPrompt` → `agent.start`, and `stop` → `agent.end`. Tool-event matchers are regular expressions against the Amp tool name; definitions with a matcher on any lifecycle event are skipped with a warning. A failing `preToolUse` command rejects the tool call and lets the agent continue; other mapped events observe the command result.\n\n> **Amp command syntax:** Amp executes plugin commands with [Bun Shell](https://bun.com/docs/runtime/shell), whose syntax differs slightly from POSIX shells. Use `$VAR` for environment expansion (`${VAR}` remains literal) and `$(command)` for command substitution (backticks remain literal). Rulesync passes the authored command through unchanged so quoting and escaped operators retain their Bun Shell meaning.\n\n> **Note:** GitHub Copilot\'s format uses separate `powershell` and `bash` fields for hooks. Rulesync supports only a single `command` field and resolves this by emitting the command under the `powershell` key on Windows, and under the `bash` key on all other platforms.\n\n> **Note:** Hook file paths per tool:\n>\n> - **Copilot (cloud agent / VS Code)** — project: `/.github/hooks/copilot-hooks.json`; global: `~/.copilot/hooks/copilot-ide-hooks.json`. VS Code and the coding agent both document `~/.copilot/hooks` as the user scope and load every `*.json` in that folder; the Copilot CLI\'s global file already occupies `copilot-hooks.json` there, so the VS Code target uses a distinct filename and the two never overwrite each other. Note the flip side of "every `*.json` is loaded": generating **both** `copilot` and `copilotcli` in global mode leaves two files in that one folder, and a reader of the folder runs the hooks from both — so a command present in your canonical config fires twice per event. Generate only one of the two globally unless you want that.\n> - **Copilot CLI** — project: `/.github/hooks/copilotcli-hooks.json`; global: `~/.copilot/hooks/copilot-hooks.json`. The Copilot CLI docs let you choose any filename inside `.github/hooks/`, so Rulesync uses the CLI-specific name to avoid colliding with the cloud-agent file when both targets are enabled. The global path is a Rulesync convention; the official Copilot CLI documentation does not currently enumerate a global hooks location, so this placement may change if the spec later mandates an alternate layout. Copilot CLI uses a **wider event surface** than the shared cloud-agent set (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `agentStop` ← `stop`, `subagentStart`, `subagentStop`, `errorOccurred` ← `afterError`, `preCompact`, `permissionRequest`, `notification`, `userPromptTransformed` ← `userPromptExpansion`, `preMcpToolCall` ← `beforeMCPExecution`) and supports three hook types: **`command`** (`bash`/`powershell` with optional `timeoutSec`, plus pass-through `cwd`/`env`; on import the portable `command` field is read as the cross-platform fallback when neither shell field is present, and `timeout` is honored as an alias for `timeoutSec` when `timeoutSec` is absent. On generate the canonical `shell` selector chooses `bash` or `powershell`; without it the portable `command` field is written, so the generated file does not depend on the machine Rulesync ran on), **`prompt`** (a `prompt` string — Copilot CLI only honors prompt hooks on `sessionStart`, so prompt hooks on other events are dropped), and **`http`** (`url`/`headers`/`allowedEnvVars` with optional `timeoutSec`). An entry\'s optional `matcher` field is emitted and round-tripped on the six events the hooks reference documents as matcher-aware — `preToolUse` and `postToolUse` (regex on the tool name), `permissionRequest` (tool name), `notification` (notification type), `preCompact` (the trigger, `manual` or `auto`) and `subagentStart` (agent name); on any other event a matcher is dropped with a warning because the CLI does not honor it there. See the [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference).\n> - **Antigravity IDE / Antigravity CLI** — project: `/.agents/hooks.json`; global: `~/.gemini/config/hooks.json`. Both targets share the same dedicated `hooks.json` (a Claude-Code-style matcher map nested under a generated `rulesync` hook name), so enabling both writes the same file.\n> - **Devin Desktop (formerly Windsurf)** — project: `/.windsurf/hooks.json`; global: `~/.codeium/windsurf/hooks.json`. The Cascade Hooks file location is unchanged by the Devin Desktop rebrand.\n> - **AugmentCode** — project: `/.augment/settings.json`; global: `~/.augment/settings.json`. Hooks are merged under the top-level `hooks` key of the shared settings file (which also holds `toolPermissions`).\n> - **Kimi Code** — global only: `~/.kimi-code/config.toml`. Hooks are merged into the shared `[[hooks]]` array without replacing unrelated model, provider, or permission settings.\n> - **Vibe Code** — project: `/.vibe/hooks.toml`; global: `~/.vibe/hooks.toml`. Stable since v2.21.0, which removed the `enable_experimental_hooks` flag: declaring a hook is enough, so Rulesync writes nothing into `.vibe/config.toml` for hooks.\n\n> **Note:** Because each AI tool evolves its own hook surface at its own pace, the matrix above reflects the events Rulesync currently translates. When a tool ships a new event that Rulesync does not yet support, the most reliable path is to open an issue — the matrix is the intended baseline to compare against.\n\n> **Note:** Kiro hooks are emitted into `.kiro/agents/default.json` under the `hooks` field, merging with any existing agent configuration (tools, allowedTools, etc.). Both `sessionEnd` and `stop` canonical events map to Kiro CLI\'s `stop` event. Only `command`-type hooks are supported; `prompt`-type hooks are silently skipped. Kiro CLI uses `timeout_ms` (in milliseconds) for per-hook timeouts and `cache_ttl_seconds` for successful-result caching; Rulesync maps the latter to the canonical `cacheTtl` field in both directions.\n\n> **Note:** Antigravity (IDE and CLI) writes a dedicated `hooks.json` keyed by a **named hook** whose value holds the event map, e.g. `{ "rulesync": { "PreToolUse": [ { "matcher": "...", "hooks": [...] } ], "Stop": [ { "hooks": [...] } ] } }`. Rulesync emits a single generated hook under the stable name `rulesync`. It supports five lifecycle events — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `preModelInvocation` ⇄ `PreInvocation`, `postModelInvocation` ⇄ `PostInvocation`, and `stop` ⇄ `Stop` — where `PreInvocation`/`PostInvocation`/`Stop` are matcher-less handler lists. On import, both the named-hook wrapper and a legacy flat top-level event map are accepted, and the optional per-hook `enabled` flag is ignored.\n\n> **Note:** Devin Desktop (formerly Windsurf) Cascade Hooks (GA) are written to a dedicated `hooks.json` whose top-level `hooks` key maps each Cascade event name to a **flat array** of hook objects (no `matcher`, no `type`, no inner `hooks` wrapper, and no `timeout`). Each object carries `command` and/or `powershell`, plus optional `show_output` and `working_directory`. Rulesync splits the generic tool lifecycle into Devin\'s file/command/MCP-specific events, so the canonical events map bijectively: `beforeReadFile` ⇄ `pre_read_code`, `beforeTabFileRead` ⇄ `post_read_code`, `afterTabFileEdit` ⇄ `pre_write_code`, `afterFileEdit` ⇄ `post_write_code`, `beforeShellExecution` ⇄ `pre_run_command`, `afterShellExecution` ⇄ `post_run_command`, `beforeMCPExecution` ⇄ `pre_mcp_tool_use`, `afterMCPExecution` ⇄ `post_mcp_tool_use`, `beforeSubmitPrompt` ⇄ `pre_user_prompt`, `afterAgentResponse` ⇄ `post_cascade_response`, `beforeAgentResponse` ⇄ `post_cascade_response_with_transcript`, and `worktreeCreate` ⇄ `post_setup_worktree`. Canonical events with no Devin equivalent (e.g. `sessionStart`, `stop`) are dropped with a logged warning. The Cascade Hooks file location (`.windsurf/hooks.json` / `~/.codeium/windsurf/hooks.json`) is retained from the Windsurf era and is unaffected by the rebrand.\n\n> **Note:** AugmentCode (Auggie CLI) hooks are merged under the top-level `hooks` key of the shared `.augment/settings.json` (project) / `~/.augment/settings.json` (global), mirroring Claude Code\'s per-event matcher arrays (`{ "EventName": [ { "matcher": "...", "hooks": [ { "type": "command", "command": "...", "timeout": ... } ] } ] }`). The `hooks` block is merged in place so it coexists with the `toolPermissions` block from the permissions feature. Seven lifecycle events are supported — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `notification` ⇄ `Notification`, and `beforeSubmitPrompt` ⇄ `PromptSubmit` (added in Auggie 0.27.0). The `matcher` field (a case-sensitive regex, default `.*`, with `mcp:*` support) applies only to the tool events `PreToolUse`/`PostToolUse`; any matcher on the session events (including `Notification` and `PromptSubmit`) is dropped with a logged warning. Two Auggie-specific fields round-trip as well: a command hook\'s `args` (extra argv the runner appends, authored as `args` on the canonical hook) and the matcher group\'s `metadata` (`includeConversationData` / `includeMCPMetadata` / `includeUserContext`, which select what the runner puts in the JSON payload the script receives). `metadata` belongs to the group upstream, so it is authored on any hook of the group and re-applied to every hook of that group on import. Both matter because the `hooks` key is owned in the shared settings file: a value not written here is erased from a hand-written `settings.json` on the next generate. Commands are emitted verbatim — Auggie exposes `AUGMENT_PROJECT_DIR` as a runtime environment variable, not as an inline command substitution, so no directory prefix is added. Only `command`-type hooks are supported. On **import** (project scope), Rulesync also reads the layered overrides file `/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before importing, following Auggie\'s documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including the `hooks` events — are combined across tiers), so personal hook overrides are picked up without dropping base events. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json`, AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode.\n\n> **Note:** Vibe Code (mistral-vibe) hooks are written to a dedicated `.vibe/hooks.toml` (project) / `~/.vibe/hooks.toml` (global) as a flat `[[hooks]]` TOML array. Each entry carries its own event `type`, a `command`, and optional `name`, `timeout` (seconds, default 60), and `description`. Tool-hook entries (`pre_tool` / `post_tool`) additionally carry a tool-name `match` (an fnmatch glob like `bash`/`mcp_*` or a `re:`-prefixed regex, case-insensitive — the canonical `matcher` field; `*` means "any tool") and an optional `strict` flag; `post_agent` carries neither. Three events are supported — `preToolUse` ⇄ `pre_tool`, `postToolUse` ⇄ `post_tool`, and `stop` ⇄ `post_agent` (fires after every assistant turn that ends without pending tool calls). Only `command`-type hooks are emitted. Vibe v2.21.0 graduated hooks from experimental: it renamed all three types (`before_tool` → `pre_tool`, `after_tool` → `post_tool`, `post_agent_turn` → `post_agent`) and removed the `enable_experimental_hooks` flag, so declaring a hook is enough and Rulesync no longer writes an auxiliary `.vibe/config.toml`. `HookType` is a strict enum upstream, so an entry using an old name is rejected outright.\n\n> **Note:** Goose hooks follow the Open Plugins spec: Rulesync writes a plugin directory `hooks/hooks.json` that Goose auto-discovers at startup. Locations are `/.agents/plugins/rulesync/hooks/hooks.json` (project) and `~/.agents/plugins/rulesync/hooks/hooks.json` (global). The JSON shape matches Claude Code\'s (`{ "hooks": { "EventName": [ { "matcher": "...", "hooks": [ { "type": "command", "command": "..." } ] } ] } }`). Eleven lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `stop` ⇄ `Stop`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `beforeReadFile` ⇄ `BeforeReadFile`, `afterFileEdit` ⇄ `AfterFileEdit`, `beforeShellExecution` ⇄ `BeforeShellExecution`, and `afterShellExecution` ⇄ `AfterShellExecution` — matching Goose\'s `HookEvent` enum exactly (it has no `SubagentStart`/`SubagentStop`). The `matcher` regex is preserved, commands are emitted verbatim (Goose exposes `PLUGIN_ROOT` as a runtime environment variable), and only `command`-type hooks are supported.\n\n> **Note:** Qwen Code hooks are written under the top-level `hooks` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global), using Claude-style PascalCase per-matcher arrays (`{ "EventName": [ { "matcher": "...", "sequential": false, "hooks": [ { "type": "command", "command": "...", "timeout": ... } ] } ] }`). Qwen\'s supported event set **differs from Gemini CLI\'s**, so rulesync defines a Qwen-specific mapping. Twenty-one lifecycle events are supported — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `postToolBatch` ⇄ `PostToolBatch`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `userPromptExpansion` ⇄ `UserPromptExpansion`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, `postCompact` ⇄ `PostCompact`, `permissionRequest` ⇄ `PermissionRequest`, `permissionDenied` ⇄ `PermissionDenied`, `notification` ⇄ `Notification`, `instructionsLoaded` ⇄ `InstructionsLoaded`, `todoCreated` ⇄ `TodoCreated`, `todoCompleted` ⇄ `TodoCompleted`, and `messageDisplay` ⇄ `MessageDisplay` (fires repeatedly as the reply streams; added in Qwen Code v0.19.10). Commands are emitted verbatim (no `$GEMINI_PROJECT_DIR` rewriting). Qwen\'s four hook types are supported: `command`, `prompt` (which carries the required `prompt` body — with `$ARGUMENTS` interpolation — and an optional `model` override, both round-tripped; a prompt hook without a `prompt` is warned about at generate time since Qwen Code loads it and fails it at runtime), `http` (which carries a `url` and POSTs JSON to it; the type and URL round-trip), and `function`. Per-hook fields added in [Qwen Code PR #2827](https://github.com/QwenLM/qwen-code/pull/2827) round-trip as well: command hooks carry `async` (run in the background), `env` (extra subprocess environment variables), and `shell` (`bash`/`powershell`); http hooks carry `headers` (with `${VAR}` interpolation), `allowedEnvVars` (the env-var allowlist), and `once` (single execution per event per session); `statusMessage` (progress text) applies to both. Command-only fields are emitted only on command hooks and http-only fields only on http hooks. The group-level `sequential` flag (parallel by default) and the top-level `disableAllHooks` switch are both round-tripped, and other top-level keys in `settings.json` are preserved. See the [Qwen Code hooks docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/hooks.md).\n\n> **Note:** Reasonix hooks are written to a dedicated `.reasonix/settings.json` (project) / `~/.reasonix/settings.json` (global) — a Claude-Code-style but standalone JSON file, separate from the `[permissions]`/`[[plugins]]` TOML config. Unlike Claude Code, each event key maps directly to a **flat array** of hook objects (no `matcher`/`hooks` wrapper): `{ "EventName": [ { "match": "...", "command": "...", "description": "...", "timeout": ... } ] }`. All ten of Reasonix\'s documented events are mapped — `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `stop` ⇄ `Stop`, `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `subagentStop` ⇄ `SubagentStop`, `postModelInvocation` ⇄ `PostLLMCall`, `notification` ⇄ `Notification`, and `preCompact` ⇄ `PreCompact`. `match` (Reasonix\'s matcher field name) is honored only on `PreToolUse`/`PostToolUse`; a matcher on any other event is dropped with a warning. The canonical `timeout` field is documented in seconds, while Reasonix\'s `timeout` is milliseconds, so rulesync converts (`× 1000` on generate, `÷ 1000` on import). Only `command`-type hooks are supported. The `settings.json` file is not documented as holding anything besides hooks today, but rulesync merges non-destructively and never deletes it, in case a future Reasonix version adds other keys. See the [Reasonix Hooks guide](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/DESKTOP_HOOKS.zh-CN.md).\n\n> **Note:** Grok CLI (xAI Grok Build) hooks are written to a dedicated, standalone `rulesync.json` that Grok auto-discovers from `.grok/hooks/*.json` (project) / `~/.grok/hooks/*.json` (global). The JSON shape is Claude-Code-compatible: each event nests under the top-level `hooks` key as a per-matcher array (`{ "hooks": { "EventName": [ { "matcher": "...", "hooks": [ { "type": "command", "command": "...", "timeout": ... } ] } ] } }`). All fourteen documented events map 1:1 onto canonical arms — `sessionStart` ⇄ `SessionStart`, `sessionEnd` ⇄ `SessionEnd`, `beforeSubmitPrompt` ⇄ `UserPromptSubmit`, `preToolUse` ⇄ `PreToolUse`, `postToolUse` ⇄ `PostToolUse`, `postToolUseFailure` ⇄ `PostToolUseFailure`, `permissionDenied` ⇄ `PermissionDenied`, `stop` ⇄ `Stop`, `stopFailure` ⇄ `StopFailure`, `notification` ⇄ `Notification`, `subagentStart` ⇄ `SubagentStart`, `subagentStop` ⇄ `SubagentStop`, `preCompact` ⇄ `PreCompact`, and `postCompact` ⇄ `PostCompact`. A `matcher` (a regex tested against the tool name) is honored on the tool-name events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionDenied`), matching Claude Code\'s semantics; a matcher on any other event is dropped with a warning. Commands are emitted verbatim (Grok documents no project-directory variable). See the [Grok hooks docs](https://docs.x.ai/build/features/hooks). Both handler types Grok defines round-trip: a `command` hook runs a command, and an `http` hook POSTs the payload to its `url`. Note that a `.rulesync/hooks.*` obtained with `rulesync fetch` can therefore point a Grok hook at any URL — read it before generating.\n\n> **Note:** Kimi Code hooks are global-only and written as flat `[[hooks]]` entries in `~/.kimi-code/config.toml`, with `event`, `command`, and optional `matcher`/`timeout`. Rulesync maps fourteen canonical lifecycle events to Kimi\'s PascalCase names: `sessionStart`, `sessionEnd`, `beforeSubmitPrompt`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `permissionRequest`, `stop`, `stopFailure`, `notification`, `subagentStart`, `subagentStop`, `preCompact`, and `postCompact`. Kimi\'s native `PermissionResult` and `Interrupt` events have no canonical equivalents, but they can be preserved in the `kimi-code.hooks` override. Only `command` hooks are emitted. Kimi normally runs these user-level hooks with each current session project as the working directory, which would let an unrelated repository substitute a relative script or influence commands such as `npm test`. Rulesync therefore wraps every generated command so it first changes to the trusted absolute directory containing the source `.rulesync/hooks.jsonc`; relative paths and project-aware commands consistently resolve against that source rather than whichever repository Kimi later opens. Kimi requires `timeout` to be an integer from 1 to 600 seconds; invalid canonical values are omitted with a warning so Kimi can still load the config. The shared TOML file is merged in place and never deleted. See the [Kimi Code hooks docs](https://moonshotai.github.io/kimi-code/en/customization/hooks.html).\n\n## `.github/mcp.json` and `.copilot/mcp-config.json`\n\nExample:\n\n```json\n{\n "mcpServers": {\n "serena": {\n "type": "stdio",\n "command": "uvx",\n "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"]\n },\n "github": {\n "type": "http",\n "url": "http://localhost:3000/mcp"\n },\n "local-dev": {\n "type": "local",\n "command": "node",\n "args": ["scripts/start-local-mcp.js"]\n }\n }\n}\n```\n\nThis file is used by the GitHub Copilot CLI for MCP server configuration. Rulesync manages it by converting from the unified `.rulesync/mcp.jsonc` format. Both scopes use the same `{ "mcpServers": {...} }` shape but write to different paths:\n\n- **Project mode:** `.github/mcp.json` (relative to project root) — the Copilot CLI auto-loads MCP servers from this workspace config file ([changelog v1.0.61, 2026-06-09](https://github.com/github/copilot-cli)).\n- **Global mode:** `~/.copilot/mcp-config.json` (relative to home directory) — the personal/global MCP configuration.\n\n> **Migration note:** earlier Rulesync versions wrote the **project-mode** Copilot CLI MCP config to `.copilot/mcp-config.json` (the same path used for global mode). Project mode now writes the dedicated workspace file `.github/mcp.json` instead, so a previously generated project-scope `.copilot/mcp-config.json` is no longer managed and can be removed by hand.\n\nRulesync preserves explicit `type` values for `http`, `sse`, and `local` servers. For command-based servers that omit a transport type, Rulesync emits the mandatory `"type": "stdio"` field required by the Copilot CLI. `streamable-http` is written as `http`, the transport it names, and the canonical `httpUrl` alias is normalized to the `url` Copilot CLI reads. A server the Copilot CLI config cannot express is skipped with a warning rather than failing the run: one that declares no transport at all (the shape a Kilo `{"enabled": …}` toggle imports as, which switches off a server some other config layer defines — every entry here defines a server), one that names a remote transport but no `url`/`httpUrl`, one that names a local transport but no `command`, and a `ws` server, since Copilot CLI has no WebSocket transport.\n\n## `rulesync/commands/*.md`\n\nExample:\n\n```md\n---\ndescription: "Review a pull request" # command description\ntargets: ["*"] # * = all, or specific tools\ncopilot: # copilot specific parameters (optional)\n description: "Review a pull request"\n agent: "agent" # (optional) VS Code prompt-file agent: "ask", "agent", "plan", or a custom agent name (replaces the deprecated "mode")\nantigravity: # antigravity specific parameters\n trigger: "/review" # Specific trigger for workflow (renames file to review.md)\n turbo: true # (Optional, default: true) Append // turbo for auto-execution\ntakt: # takt specific parameters (optional; emitted under .takt/facets/instructions/)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\n extends: "base" # (optional) emit a leading `{extends:}` facet-inheritance directive (Takt 0.39.0+)\npi: # pi coding agent specific parameters (optional)\n argument-hint: "[message]" # Hint shown in Pi\'s command palette\ncodexcli: # Codex CLI custom-prompt specific parameters (optional)\n argument-hint: "[message]" # Hint shown for the custom prompt\'s arguments\nroo: # Roo Code specific parameters (optional)\n mode: "architect" # (optional) mode slug to switch to before running the command body (e.g. "code", "architect")\n---\n\ntarget_pr = $ARGUMENTS\n\nIf target_pr is not provided, use the PR of the current branch.\n\nExecute the following in parallel:\n\n...\n```\n\nThe command body itself uses a Claude Code-compatible **universal syntax** (e.g. `$ARGUMENTS`, `` !`cmd` ``). When a target tool expects a different placeholder syntax, rulesync translates it automatically on generation and reverses the translation on import. See [Command Syntax](./command-syntax.md) for the full mapping.\n\n> **Codex CLI deprecation note:** Codex CLI\'s own docs now state "Custom prompts are deprecated. Use skills for reusable instructions" (see [Custom Prompts](https://developers.openai.com/codex/custom-prompts)). Rulesync\'s `codexcli` commands still generate the global-only `~/.codex/prompts/*.md` custom-prompt files described above — they remain functional and no removal date has been announced, so this behavior is unchanged for now. For new reusable instructions, prefer rulesync\'s `codexcli` skills support (see `.rulesync/skills/*/SKILL.md` below) instead.\n\n> **Warp note:** Warp documents skills as its custom slash-command surface — any skill is invocable as `/{skill-name}` with `$ARGUMENTS` / `$ARGUMENTS[N]` / `$N` argument substitution — so rulesync emits each command onto the native skills surface as `.warp/skills//SKILL.md` (project) / `~/.warp/skills//SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. Warp\'s `.warp/workflows/` YAML files are parameterized shell-command templates, not agent prompts, and are deliberately not used. Commands import and `--delete` are no-ops for `warp` because the skills feature owns the `.warp/skills/` tree (importing it as commands would double-import every skill) — mirrors the Devin note below. Keep command and skill names distinct for this target, since a command and a skill sharing a name write the same `SKILL.md` path. See the [Warp skills docs](https://docs.warp.dev/agent-platform/capabilities/skills/).\n\n> **Devin note:** Devin\'s extensibility docs no longer document a standalone workflows/commands component — reusable prompts invoked as slash commands are [Skills](https://docs.devin.ai/cli/extensibility/skills/overview) (`/name`). Rulesync therefore emits each command onto the native skills surface as `.devin/skills//SKILL.md` (project) / `~/.config/devin/skills//SKILL.md` (global, via `--global`), with `name`/`description` frontmatter derived from the command file. The legacy Windsurf/Cascade-era `.devin/workflows/` and `~/.codeium/windsurf/global_workflows/` locations are no longer emitted (stale outputs there stay gitignored but are not cleaned up automatically). Commands import and `--delete` are no-ops for `devin` because the skills feature owns the `.devin/skills/` tree (importing it as commands would double-import every skill). Note that a command and a skill sharing the same name write the same `SKILL.md` path, so keep command and skill names distinct for this target.\n\n> **Agent Skills standard note (`agentsskills`):** Rulesync accepts the legacy rulesync spellings on input but always **emits** the shapes the [specification](https://agentskills.io/specification) requires: `allowed-tools` becomes a space-separated scalar (a YAML list is joined), `compatibility` becomes a string (an object is flattened to `key: value` pairs), and `metadata` values are stringified so the block stays a string→string map. Generation also checks the normative constraints and warns — without failing the run — when `name` is empty, longer than 64 characters, contains anything but lowercase letters, digits and single hyphens, or does not match its parent directory name; when `description` is empty or longer than 1024 characters; when `compatibility` exceeds 500 characters; or when an `allowed-tools` list entry contains whitespace, which the space-separated form cannot represent. These are warnings rather than errors because a conformant client only _skips_ such a skill, and because import stays lenient as the [client-implementation guide](https://agentskills.io/client-implementation/adding-skills-support) advises. A value that normalizes to the empty string (`compatibility: {}`, `allowed-tools: []`) is dropped rather than written, since the spec requires `compatibility` to be 1–500 characters when present. On **import**, `allowed-tools` is normalized back to the canonical rulesync list, so a generate → import round trip leaves `.rulesync/skills/**` in the shape it started in (the `compatibility` and `metadata` coercions are one-way, because the legacy object/number forms have no conformant equivalent). `hermesagent` reads the same `agentsskills` block and applies the same normalization in both directions, so one rulesync source never produces two different on-disk spellings — except for `metadata`, which stays structured there because Hermes reads `metadata.hermes.*` as YAML. A `hermesagent:` override still wins over the shared block (as for every tool-specific section), so a list or mapping written there is emitted as-is and reported as a spec violation rather than rewritten. Validate the result with the spec\'s own [`skills-ref validate`](https://github.com/agentskills/agentskills/tree/main/skills-ref). Import leniency is root-based as well as tool-based: any tool scanning an Agent Skills interop root (project `.agents/skills/`, global `~/.agents/skills/`, or Amp\'s `~/.config/agents/skills/`) skips-and-warns on a skill (directory-form or flat-file) that fails to load there — the cross-vendor directory is where foreign-authored, potentially non-conformant skills live — while each tool\'s own native root (e.g. Rovo Dev\'s `.rovodev/skills/`) stays fail-fast.\n\n> **Replit note:** Replit\'s skills page states conformance to the [Agent Skills specification](https://agentskills.io/specification), so `replit.allowed-tools` accepts either the spec\'s space-separated string or a canonical rulesync list and is always **emitted** as the string; `replit.compatibility` likewise accepts the spec\'s string alongside the legacy object form. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents` — so keep list entries free of whitespace, since the space-separated form cannot represent an entry such as `Bash(git commit:*)` and a client would read it back as two. An object `compatibility` is emitted unchanged rather than flattened: unlike the join, that conversion would be one-way, so the legacy form stays as-is and is simply not spec-conformant on disk.\n\n> **Vibe skills note:** Vibe discovers skills under `.vibe/skills/` (project) and `~/.vibe/skills/` (global), plus the shared `.agents/skills/` root at **both** scopes — Vibe\'s `user_skills_dirs` returns `~/.vibe/skills` and `~/.agents/skills` alike. Rulesync registers the shared root as an import fallback at either scope; it is import-only and is never removed by Vibe-target orphan deletion.\n\n> **Pi skills note:** Pi implements the [Agent Skills specification](https://agentskills.io/specification), so `pi.allowed-tools` accepts either the spec\'s space-delimited string or a canonical rulesync list and is always **emitted** as the string; `pi.compatibility` likewise accepts the spec\'s string alongside the legacy object form. Importing a spec-conformant `SKILL.md` used to fail outright. On import, `allowed-tools` is normalized back to the list, mirroring `deepagents`; keep list entries free of whitespace, since the space-delimited form cannot represent an entry such as `Bash(git commit:*)`. An `allowed-tools` value that normalizes to the empty string (an empty list) is dropped rather than written. An object `compatibility` is emitted unchanged rather than flattened, because that conversion would be one-way.\n\n> **Hermes Agent note:** Commands are global-only and remain distinct from skills. Rulesync writes JSON command specs to `~/.hermes/rulesync/commands/.json`, installs the `rulesync-commands` plugin under `~/.hermes/plugins/`, and enables it in `~/.hermes/config.yaml`. The plugin registers each spec with Hermes\'s [`ctx.register_command()` plugin API](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/) and dispatches the prompt through `delegate_task`; invocation arguments are appended to the prompt. `.rulesync/skills//SKILL.md` still generates a full [Hermes Agent Skill](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills/) under `~/.hermes/skills//SKILL.md`, which Hermes also exposes as a dynamic slash command. Rulesync rejects command/skill names that would collide in Hermes\'s slash-command namespace, and rejects nested command paths that flatten to the same name. Generate commands with `rulesync generate --targets hermesagent --features commands --global`.\n>\n> Releases before this native plugin transport emitted Hermes commands as `~/.hermes/skills//SKILL.md`. Rulesync cannot distinguish those files from real user-authored skills safely, so remove an obsolete legacy file manually after confirming that `.rulesync/skills//SKILL.md` does not own it.\n\n> **Qwen Code note:** Custom commands are emitted as **Markdown** files (not TOML — TOML is deprecated upstream) under `.qwen/commands/` (project) and `~/.qwen/commands/` (global, via `--global`). The file is an optional YAML frontmatter block followed by the prompt body; besides `description`, Qwen Code\'s command loader reads `when_to_use` (invocation guidance), `argument-hint` (completion hint), and `disable-model-invocation`, all typed and round-tripped. Subdirectory namespacing is supported: `.qwen/commands/git/commit.md` becomes the `/git:commit` command. Any extra fields are preserved on round-trip under the `qwencode:` block.\n\n> **OpenCode import note:** OpenCode lets commands live both as Markdown files under `.opencode/commands/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `command` key. On import, rulesync reads both: each inline entry\'s `template` becomes the command body and its `description`/`agent`/`model`/`subtask` fields become frontmatter. A Markdown file takes precedence over an inline entry with the same name.\n\n> **AugmentCode note:** Commands are written to `.augment/commands/.md` (project) / `~/.augment/commands/.md` (global, via `--global`). Subdirectories are namespaces — `.augment/commands/git/commit.md` is `/git:commit` — so nested rulesync commands keep their nesting rather than being flattened to a basename. If you generated AugmentCode commands with an earlier Rulesync, the flattened files it wrote are still on disk under their old names; `--delete` removes them. Auggie also discovers commands under the cross-tool `.agents/commands/` root, so **import** reads that root too and treats a command found there as if it lived under `.augment/commands/` — the command\'s name is its path under whichever root it came from. Generation stays on `.augment/commands/`, and `.agents/commands/` is never written to or swept for orphans, since the files there may belong to another tool — Rulesync itself writes that root for the `agentsmd` target, so a command already imported from `.augment/commands/` is not imported again from there under a flattened name. Auggie\'s other shared root, `.claude/commands/`, is deliberately not read: it is Claude Code\'s own output, which Rulesync already imports as that target. Importing from a shared root is announced, because the result is a Rulesync command written for every target on the next generate. See the [custom commands docs](https://docs.augmentcode.com/cli/custom-commands).\n\n> **Reasonix note:** Custom slash commands are Markdown files under `.reasonix/commands/` (project) / `~/.reasonix/commands/` (global, via `--global`) — directly analogous to Claude Code\'s `.claude/commands/`, since Reasonix explicitly mirrors Claude Code\'s conventions. Frontmatter supports `description` and `argument-hint`, and the body uses the same `$ARGUMENTS` / `$1`…`$N` placeholder syntax. Subdirectory namespacing is supported (`git/commit.md` → `/git:commit`). Any extra fields are preserved on round-trip under the `reasonix:` block. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md#slash-commands).\n\n> **Grok CLI note:** Custom slash commands are Markdown files under `.grok/commands/` (project) / `~/.grok/commands/` (global, via `--global`), read by the same Claude-Code-compatible frontmatter parser Grok uses for skills. Rulesync emits `description` plus, from the `grokcli:` block, `argument-hint`, `user-invocable` (default true) and `disable-model-invocation` (default false) — the same invocation-control pair Grok skills honor. Two upstream constraints are worth knowing. Grok\'s command scan is **flat and non-recursive**, so subdirectory namespacing is not supported: a nested `git/commit.md` is flattened onto `commit.md`, and two nested commands with the same basename collide (rulesync warns and the last one wins). And Grok collects skills before commands, letting **skills win name collisions** — a `.grok/skills//` shadows `.grok/commands/.md`, so avoid giving a rulesync skill and a rulesync command the same name when targeting Grok. Any extra frontmatter keys are preserved on round-trip under the `grokcli:` block. See the [skills, plugins and marketplaces docs](https://docs.x.ai/build/features/skills-plugins-marketplaces).\n\n> **Rovo Dev CLI note:** Rovo Dev\'s "saved prompts" are a file-based custom-command surface made of a `prompts.yml` manifest plus per-prompt Markdown content files, invoked via `/prompts [title] [extra]`. Rulesync writes the content (no frontmatter) to `.rovodev/prompts/.md` (project) / `~/.rovodev/prompts/.md` (global, via `--global`), and rebuilds the sibling `.rovodev/prompts.yml` / `~/.rovodev/prompts.yml` manifest with one `{ name, description, content_file }` entry per prompt, `content_file` pointing at `prompts/.md` (resolved relative to `prompts.yml`, matching Rovo Dev\'s own resolution order). The `prompts` array is fully replaced from the current rulesync commands on each generate (mirrors the Rovodev MCP adapter fully replacing `mcpServers`); any other top-level key in an existing manifest is preserved, and the manifest is never deleted. See the [saved prompts](https://support.atlassian.com/rovo/docs/save-and-reuse-a-prompt-in-rovo-dev-cli/) and [CLI commands](https://support.atlassian.com/rovo/docs/rovo-dev-cli-commands/) docs.\n\n## `rulesync/subagents/*.md`\n\nExample:\n\n```md\n---\nname: planner # subagent name\ntargets: ["*"] # * = all, or specific tools\ndescription: >- # subagent description\n This is the general-purpose planner. The user asks the agent to plan to\n suggest a specification, implement a new feature, refactor the codebase, or\n fix a bug. This agent can be called by the user explicitly only.\nclaudecode: # for claudecode-specific parameters\n model: inherit # opus, sonnet, haiku, fable, a full model id, or inherit (default)\n tools: ["Read", "Write"] # (optional) allowed tools (string or list)\n disallowedTools: ["Bash"] # (optional) tools to remove (string or list)\n permissionMode: default # (optional) default | acceptEdits | bypassPermissions | plan\n maxTurns: 20 # (optional) maximum agentic turns\n skills: ["skill-creator"] # (optional) Agent Skills to utilize (string or list)\n color: cyan # (optional) UI color (e.g. red, blue, green, cyan, ...)\n memory: project # (optional) user | project | local\n effort: high # (optional) low | medium | high | xhigh | max\n isolation: worktree # (optional) run the subagent in an isolated git worktree\n background: false # (optional) run the subagent in the background\n initialPrompt: "Start by reading the spec." # (optional) seed prompt for the subagent\n mcpServers: {} # (optional) MCP server config (passed through verbatim)\n hooks: {} # (optional) hook config (passed through verbatim)\ncopilot: # for GitHub Copilot specific parameters\n tools:\n # Listed tools are emitted verbatim; omit `tools` entirely to grant the agent\n # all tools. `agent/runSubagent` is opt-in — add it explicitly only when this\n # subagent needs to orchestrate other subagents.\n - web/fetch\n - agent/runSubagent\nopencode: # for OpenCode-specific parameters\n mode: subagent # (optional, defaults to "subagent") OpenCode agent mode\n model: anthropic/claude-sonnet-4-20250514\n temperature: 0.1\n tools:\n write: false\n edit: false\n bash: false\n permission:\n bash:\n "git diff": allow\nkilo: # for Kilo-specific parameters\n mode: all # (optional, defaults to "all") use "subagent" for hidden/subagent-only agents\ncursor: # for Cursor-specific parameters (generated to .cursor/agents/*.md)\n model: inherit # (optional, defaults to "inherit") model id, or "inherit" to use the parent\'s model\n readonly: false # (optional, defaults to false) restrict the subagent to read-only tools\n is_background: false # (optional, defaults to false) run the subagent as a background agent\njunie: # for JetBrains Junie CLI specific parameters (generated to .junie/agents/*.md; also imported from .agents/*.md)\n tools: ["Read", "Grep", "Edit"] # allowed tools\n disallowedTools: ["Bash", "WebSearch"] # disallowed tools\n mcpServers: ["github"] # MCP servers the subagent may use\n model: sonnet # model id\n reasoningLevel: high # low | medium | high\n maxTurns: 20 # max agentic turns\n skills: ["kotlin", "writerside"] # Agent Skills to utilize\n allowPromptArgument: true # whether the subagent accepts a prompt argument\ntakt: # takt specific parameters (optional; emitted under .takt/facets/personas/)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\nroo: # for Roo Code specific parameters (optional; aggregated into the root .roomodes file)\n slug: planner # (optional) custom mode slug (^[a-zA-Z0-9-]+$); defaults to the sanitized file name\n whenToUse: "When planning a task" # (optional) guidance for automated mode selection\n customInstructions: "Be concise." # (optional) extra behavioral guidelines\n roleDefinition: "You are the planner." # (optional) overrides the body as the mode\'s roleDefinition\n groups: # (optional, defaults to ["read", "edit", "command", "mcp"]) tool access\n - read\n - ["edit", { fileRegex: "\\\\.md$", description: "Markdown files" }]\n---\n\nYou are the planner for any tasks.\n\nBased on the user\'s instruction, create a plan while analyzing the related files. Then, report the plan in detail. You can output files to @tmp/ if needed.\n\nAttention, again, you are just the planner, so though you can read any files and run any commands for analysis, please don\'t write any code.\n```\n\n> **Antigravity note:** Antigravity custom agents (CLI v1.1.6+, shared by the IDE and the CLI) are emitted as Markdown + YAML frontmatter to `.agents/agents/.md` (project) and `~/.gemini/config/agents/.md` (global, via `--global`); the body after the frontmatter is the agent\'s system prompt. Both `antigravity-ide` and `antigravity-cli` read the same two locations, so enabling both writes the same file — the same way they already share `.agents/hooks.json`. Antigravity also accepts a directory form (`/agent.md`); Rulesync emits and imports the flat file form only. `name` and `description` are **required** upstream, so a canonical subagent without a description gets a minimal generated fallback rather than a file Antigravity refuses to load. Because the two share that file, every Antigravity target reads the `antigravity-ide` and `antigravity-cli` blocks merged in a fixed order (the CLI block wins) — the same rule the MCP feature uses for the same shared-output reason — so generation order never changes the file\'s content; the `antigravity-plugin` block is layered on top for the plugin bundle only. Besides the shared `name`/`description`, those blocks accept these optional fields (all preserved on round-trip): `tools` (string list), `mainAgent` (boolean, default `true`), `subagent` (boolean, default `true`), `model` (`inherit` | `flash` | `pro`), `commandExecutionPolicy` (`off` | `auto` | `eager` | `sandbox`), `mcpServers`, `skills`, and `plugins`. `hidden` and `inheritMcp` appear in the v1.1.6 release notes but not in the documented frontmatter table, so they pass through verbatim with no behavior modeled around them; the schema is loose, so any extra keys survive the round-trip too. The `antigravity-plugin` target writes the same file format into a plugin bundle\'s `agents/` directory (project scope only). See the [Antigravity subagents docs](https://antigravity.google/docs/subagents) and the [plugin bundle layout](https://antigravity.google/docs/cli/plugins).\n\n> **Qwen Code note:** Subagents are emitted as Markdown + YAML frontmatter under `.qwen/agents/` (project) and `~/.qwen/agents/` (user/global, via `--global`); the body is the subagent\'s system prompt. Besides the shared `name`/`description`, the `qwencode:` block accepts these optional fields (all preserved on round-trip): `model`, `approvalMode` (`default` | `plan` | `auto-edit` | `yolo` | `bubble`), `tools` (allowlist), `disallowedTools` (denylist), `maxTurns`, `color`, `mcpServers` (per-agent MCP overrides — accepts both a record of server specs, matching Qwen\'s documented shape, and a plain array of server names), and `hooks` (per-agent hook registrations). See the [Qwen Code sub-agents docs](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/sub-agents.md).\n\n> **Kimi Code note:** Subagents are emitted as Markdown files under `.kimi-code/agents/` (project) and `~/.kimi-code/agents/` (global). The shared `name` and required `description` fields are written to YAML frontmatter; Kimi-specific `whenToUse`, `override`, `tools`, `disallowedTools`, and `subagents` fields can be authored under the `kimi-code:` block and round-trip unchanged. Kimi recursively scans both its Kimi-specific agents directory and the shared `.agents/agents/` directory, so Rulesync imports nested Markdown files from both locations and flattens them into `.rulesync/subagents/.md` using the validated kebab-case agent name. The Kimi-specific root has precedence over `.agents/agents/`; if multiple source files resolve to the same logical agent name, the first one wins and Rulesync warns about the duplicate. The shared root is import-only and is never removed by Kimi-target orphan deletion. See the [Kimi Code custom-agents docs](https://moonshotai.github.io/kimi-code/en/customization/agents.html).\n\n> **Kiro CLI note:** Subagents are emitted as JSON agent configurations under `.kiro/agents/` (project) and `~/.kiro/agents/` (global). Kiro allows the JSON `name` field to be omitted, in which case the filename stem is the agent name; Rulesync accepts that form on import and writes the derived name into the Rulesync frontmatter. Imports through the `kiro-cli` target retain `targets: ["kiro-cli"]`, so they can be generated back to the same target without changing the target metadata.\n\n> **Cline note:** Cline file-based agents are emitted as YAML files (`.yaml`) into `.cline/agents/` (project) and `~/.cline/agents/` (global, via `--global`). The file is a YAML frontmatter block followed by the system prompt body, matching Cline\'s agent config loader: `name` and `description` are **required** (Cline cli-v3.0.23+ refuses to load an agent whose `description` is missing or empty — a canonical subagent without one gets a minimal generated fallback rather than a file Cline cannot load), and the typed optional fields `tools`, `skills`, `providerId`, `modelId`, and `maxIterations` round-trip through the `cline:` section. Import reads `.yml` alongside `.yaml`, matching Cline\'s `isYamlFile()`.\n\n> **Devin note:** Devin Local custom subagent profiles are emitted as `AGENT.md` files in a **directory-per-agent** layout: `.devin/agents//AGENT.md` (project) and `~/.config/devin/agents//AGENT.md` (global, via `--global`). The directory name `` is the profile id (derived from the rulesync subagent file name). The `AGENT.md` is a YAML frontmatter block followed by the subagent\'s system prompt. Besides the shared `name`/`description`, the `devin` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, override the subagent LLM), `allowed-tools` (list of strings, restrict available tools), `permissions` (object with `allow`/`deny`/`ask` string lists, override tool permissions), and `max-nesting` (integer, enable nested subagent spawning up to the given depth). See the [Devin subagents docs](https://docs.devin.ai/cli/subagents).\n\n> **Reasonix note:** Reasonix native subagents are Skill profiles emitted as `SKILL.md` files in a **directory-per-agent** layout: `.reasonix/skills//SKILL.md` (project) and `~/.reasonix/skills//SKILL.md` (global, via `--global`). The directory name `` is the profile id (derived from the rulesync subagent file name). A subagent is a Skill whose YAML frontmatter declares `invocation: manual` and `runAs: subagent` — Rulesync always injects both markers so the SKILL.md is recognized as a manually invoked subagent rather than an auto-discovered skill. Besides the shared `name`/`description`, the `reasonix` subagent block accepts these optional fields (all preserved on round-trip): `model` (string, subagent LLM), `effort` (string, reasoning effort), `allowed-tools` (list of strings, restrict available tools), and `color` (string, display color). The schema is loose, so any extra keys survive the round-trip. See the [Reasonix subagent profiles docs](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SUBAGENT_PROFILES.md).\n\n> **Roo skills/commands note (final v3.54.0 state — Roo Code is EOL and its repository archived):** Commands are generated to `.roo/commands/` (project) and `~/.roo/commands/` (global, via `--global`; project wins on a name collision). Skill frontmatter beyond `name`/`description` — most usefully `modeSlugs: string[]` for mode targeting — is authored via the `roo:` section of `.rulesync/skills/*/SKILL.md` and lifted back into it on import, so it survives the round-trip. A localRoot rule is emitted as `AGENTS.local.md`, the personal, gitignored override file Roo loads alongside `AGENTS.md`.\n\n> **Zoo Code note:** Zoo Code ([Zoo-Code-Org/Zoo-Code](https://github.com/Zoo-Code-Org/Zoo-Code)) is the community continuation of the archived Roo Code, named by the Roo shutdown notice and continuing Roo\'s release numbering (v3.54.0 → v3.72.0 as of 2026-07-25). It still resolves `~/.roo` and the project `.roo/` layout — the `.zoo` renaming is confined to provider/auth code — so the `zoocode` target reuses the `roo` adapters\' path model verbatim across rules (including `AGENTS.local.md` local-root handling), ignore (`.rooignore`), MCP (`.roo/mcp.json`), commands (`.roo/commands/`), skills (`.roo/skills/`, `roo:` frontmatter section), and subagents (the aggregated `.roomodes` file). Shared mode/skill fields keep riding the `roo:` frontmatter sections, so one rulesync source never produces two spellings; targeting both `roo` and `zoocode` writes the same files, so pick one target per project — and note the fail-open hazard the shared `.roomodes` creates: a `--targets roo` generate rewrites it **without** `allowedMcpServers`, so opening that workspace in Zoo Code makes every MCP server available to the mode. The post-fork divergence is carried by the `zoocode:` subagent section: `allowedMcpServers` (Zoo Code v3.60.0+), a per-mode MCP server allowlist ("when omitted, all servers are available; when set, only the listed servers are injected"), emitted into the mode and lifted back into `zoocode:` on import. See the [Zoo Code docs](https://docs.zoocode.dev/features/custom-modes).\n\n> **Roo note (as of 2026-06-16):** Roo Code reads project custom modes from a single aggregated `.roomodes` file at the workspace root (YAML; JSON also accepted). Rulesync therefore collapses every Roo-targeted subagent into that file\'s `customModes` array — each subagent becomes one mode whose `slug` is derived from the file name (sanitized to `^[a-zA-Z0-9-]+$`), `name`/`description` come from the shared frontmatter, and `roleDefinition` is the subagent body. The optional `roo:` block supplies `groups` (defaults to `["read", "edit", "command", "mcp"]`), `whenToUse`, `customInstructions`, an explicit `slug`, and a `roleDefinition` override. (Roo\'s previous `.roo/subagents/` output was inert — Roo Code never read it.) See the [Roo custom-modes docs](https://roocodeinc.github.io/Roo-Code/features/custom-modes).\n\n> **OpenCode import note:** OpenCode lets agents live both as Markdown files under `.opencode/agents/*.md` **and** inline in `opencode.json`/`opencode.jsonc` under the top-level `agent` key. On import, rulesync reads both: each inline entry\'s `prompt` becomes the subagent body (a `"{file:./path}"` reference is resolved relative to the config file\'s location, as OpenCode does), and the remaining fields (`description`/`mode`/`model`/`tools`/`permission`/...) become frontmatter under the `opencode:` block. A Markdown file takes precedence over an inline entry with the same name.\n\n> **Kilo note (as of 2026-05-13):** Kilo\'s documented default for user-defined agents is `mode: all`, which makes the agent available both as a top-level pick and as a subagent. Set `kilo.mode: subagent` to opt into hidden/subagent-only behavior.\n\nBesides `mode`, the `kilo` subagent block accepts these optional fields (all preserved on round-trip):\n\n| Field | Type | Notes |\n| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `displayName` | string | Human-friendly name shown in pickers |\n| `model` | string | Model id |\n| `variant` | string | Model variant |\n| `temperature` | number | Sampling temperature |\n| `top_p` | number | Nucleus-sampling parameter |\n| `permission` | string \\| object | Permission profile name, or a per-tool `{ : { allow, deny, ask } }` object |\n| `prompt` | string | Inline system prompt |\n| `color` | string | UI color |\n| `native` | boolean | Native (built-in) agent flag |\n| `hidden` | boolean | Hide from top-level picker |\n| `disable` | boolean | Disable the agent |\n| `deprecated` | boolean | Mark as deprecated |\n| `steps` | positive integer | Maximum agentic iterations before a text-only response is forced (an explicit `null` is accepted and round-trips as-is, so a file that already carries one still imports; earlier Rulesync versions took a list of step objects here, which Kilo never accepted) |\n| `options` | object | Free-form key/value options |\n\n> **Migration note (`steps`):** earlier Rulesync versions typed `steps` as a list of step objects, which Kilo never accepted — a subagent authored that way produced a file Kilo ignored. It is now the iteration count Kilo documents, so a `kilo` block (or a `.kilo/agents/*.md` file) still carrying the list form fails validation with the offending file named, and the run stops rather than writing a file that would not work. Replace the list with the number of iterations you want, or drop the field.\n\n> **Hermes Agent note:** Project generation writes subagent JSON specs under `.hermes/rulesync/subagents/` and installs `.hermes/plugins/rulesync-subagents/`. The plugin resolves specs relative to its own installation, so the same code works in project and global scope. For project scope, Rulesync also enables `rulesync-subagents` in `$HERMES_HOME/config.yaml`. Run Hermes from the trusted project root with `HERMES_ENABLE_PROJECT_PLUGINS=true`; Rulesync deliberately does not persist that global trust gate.\n\n## `.rulesync/checks/*.md`\n\nCode review checks are per-check instructions an agent runs during code review. Each check is a single Markdown file with YAML frontmatter (the source of the check identity is the file name — e.g. `.rulesync/checks/security.md` defines the `security` check).\n\nExample:\n\n```md\n---\ntargets: ["*"] # * = all, or specific tools\ndescription: Flags common security issues # (optional) short summary of the check\nseverity: high # (optional) low | medium | high | critical\ntools: ["Read", "Grep"] # (optional) tool names the check may use\n---\n\nReview the diff for injection vulnerabilities, hardcoded secrets, and unsafe\ndeserialization. Report each finding with a file and line reference.\n```\n\nAmp, Cursor, Hermes Agent, Rovo Dev CLI and Takt consume checks. Amp receives one Markdown file per check:\n\n- **Project scope:** `.agents/checks/.md`\n- **Global scope** (`--global`): `~/.config/amp/checks/.md`\n\nFor Cursor, checks are [Bugbot](https://cursor.com/docs/bugbot) code review instructions, and Bugbot reads one aggregated instruction file per directory rather than a file per check — so every check targeting Cursor collapses into the repository-root `.cursor/BUGBOT.md`. Each check becomes one section: an HTML-comment marker carrying the check name, an `## ` heading, and the check body as the instruction text (the `description` is used when the body is empty). Bugbot reads the file as free prose, so a check\'s `severity` and `tools` have no equivalent there — they are not written and do not come back on import, and neither is `description` whenever the check also has a body. Project scope only: Bugbot reads repository files and there is no user-level instruction file. Because Bugbot only sees the file when it is **committed**, the derived `.gitignore` deliberately does not ignore `.cursor/BUGBOT.md` (Rovo Dev\'s `.rovodev/.review-agent.md` gets the same treatment) — commit the generated file for the reviewer to pick it up. Example output:\n\n```md\n\n\n## security\n\nReview the diff for injection vulnerabilities.\n```\n\nOn import the markers split the file back into one check per section, each with `targets: ["*"]` because Bugbot instructions are plain prose that applies anywhere. Content sitting ahead of the first marker — and a hand-written `BUGBOT.md` with no markers at all — is imported as a single `bugbot` check, so nothing in the file is dropped. A check body that contains a marker line of its own (a quoted rulesync doc fragment, say) is written as `` and restored on import, so it cannot split the check it belongs to. Bugbot also merges nested `/.cursor/BUGBOT.md` files found while traversing upward from changed files, but rulesync check sources carry no directory-placement semantics, so only the root file is generated.\n\nGenerating checks for Cursor replaces `.cursor/BUGBOT.md`, so run `rulesync import --targets cursor --features checks` first if the repository already has a hand-written one — generation warns when it is about to replace instructions rulesync did not write. Deletion is guarded: a `BUGBOT.md` holding anything rulesync did not write — no marker at all, or hand-written text ahead of the first marker — is never removed, so dropping the last check that targets Cursor takes rulesync\'s own output with it and nothing else.\n\nFor Rovo Dev CLI, checks are [code-review custom instructions](https://support.atlassian.com/rovo/docs/set-custom-instructions-for-code-reviews/), and Rovo Dev reads one plain-Markdown file rather than a file per check — so every check targeting Rovo Dev collapses into `.rovodev/.review-agent.md` (note the leading dot in the file name). The file takes **no frontmatter**. Everything else works exactly as it does for Cursor Bugbot above, because the two surfaces are the same shape: one marked-up section per check, `severity`/`tools` dropped, `description` used only when the body is empty, markers splitting the file back on import (with a hand-written file importing as a single `review-agent` check), the same `` escaping, the same replace-and-warn on generate, and the same deletion guard for a file holding anything rulesync did not write. Project scope only — these are per-repository review instructions and Rovo Dev documents no user-level equivalent, which is the opposite of the Rovo Dev permissions surface (global only).\n\nFor Hermes Agent, Rulesync writes project-local JSON specs under `.hermes/plugins/rulesync-checks/checks/` and a `rulesync-checks` plugin beside them. Its one-shot [`pre_verify` hook](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-verify) fires only for coding turns with changed paths and `attempt == 0`, then asks Hermes to run all configured checks before finishing. `tools` is preserved as advisory guidance because Hermes does not enforce an Amp-style per-check tool allowlist. Run Hermes with the project plugin explicitly trusted for that invocation:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-checks` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged, preserving Hermes\'s global trust boundary. Existing plugin configuration is preserved; an explicit `plugins.disabled` conflict fails generation.\n\nFor Takt, checks are **quality gates**, and they live in the `workflow_overrides` block of the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global) rather than in files of their own — so every check targeting Takt collapses into that one file. A check becomes one gate: by default a **string gate**, the body text, which Takt injects into the agent step prompt as a completion directive (the `description` is used when the body is empty, and the file stem when neither is set); with `command` in the check\'s `takt` frontmatter block, a **command gate** (`{type: command, name, command, cwd, timeout_ms}`), which Takt runs after the step and fails on a non-zero exit code. `name` defaults to the file stem so Takt\'s logs identify the gate. `name`, `cwd` and `timeout_ms` belong to a command gate, so they are ignored on a check that states no `command`. `steps` and `personas` in that block scope a gate to named workflow steps or personas (`workflow_overrides.steps..quality_gates`); an unscoped gate applies everywhere, and a gate naming both is written to both. `quality_gates_edit_only` is a property of the block as a whole, so one check setting it turns it on for all of them. It reaches only the unscoped gates — Takt runs a `steps`/`personas`-scoped gate whether or not the step may edit files — so the reach it narrows is the other checks\' unscoped gates, which is warned about when there are any. Takt gates carry no severity or tool allowlist, so a check\'s `severity` and `tools` are not written and do not come back on import. Takt merges quality gates additively and dedupes them (project over global over the workflow YAML\'s own gates). Example:\n\n```md\n---\ntargets: ["takt"]\ntakt:\n command: ./.takt/quality-gates/check.sh # omit for a string gate\n timeout_ms: 300000\n steps: ["review"] # (optional) scope to named workflow steps\n personas: ["coder"] # (optional) scope to named personas\n---\n```\n\nA command gate\'s `command` is run by Takt with no further gating — Takt\'s default-deny `workflow_command_gates.custom_scripts` policy applies to gates declared in workflow YAML, not to these — so read the frontmatter of any check you obtain with `rulesync fetch` before generating. The body of a check that carries a `command` is not used. `workflow_overrides` is owned by the checks feature: it is rewritten from `.rulesync/checks/` on every generate, so a gate deleted there disappears from `config.yaml` too, while every other key of the file is preserved and the file is never deleted. When checks remain but none of them target Takt — every one names other tools — the block is retracted with a warning, whether an earlier generate or a hand edit put it there; that is what owning the key means, so author gates as checks rather than in `config.yaml`. A project with no `config.yaml` does not get one. Emptying `.rulesync/checks/` altogether is different: the feature has no source to generate from, so nothing runs and the gates already in `config.yaml` stay. Delete the block by hand in that case — a command gate left behind keeps running after every step. On import, each gate becomes its own check file, named from the gate text or the command gate\'s `name`. A string gate is prose that applies anywhere, so it imports with `targets: ["*"]` like an Amp check; a command gate imports as `targets: ["takt"]`, since its body is empty and would generate an empty check for every other tool. A gate scoped to both a step and a persona becomes two checks, and a command gate carrying a field of the wrong type is left in `config.yaml` rather than imported. The default-deny `workflow_command_gates.custom_scripts` policy is **not** written here — Takt validates it against gates declared in workflow YAML, not against these, and it is authorable through the `takt` block of `.rulesync/permissions.*`, which owns the security policies. See the [Takt workflows docs](https://github.com/nrslib/takt/blob/main/docs/workflows.md).\n\nThe emitted Amp frontmatter is derived from the source as follows:\n\n| Amp field | Source |\n| ------------------ | -------------------------------------------------------- |\n| `name` | the source file basename without `.md` (required by Amp) |\n| `description` | `description` |\n| `severity-default` | `severity` |\n| `tools` | `tools` |\n\nThe frontmatter schema is loose, so extra Amp-specific keys survive a generate/import round-trip (except keys that collide with a rulesync tool-target name such as `cursor` — those are treated as tool-scoped sections and are not re-emitted). A tool-scoped section (e.g. `amp: { "severity-default": "critical" }`) overrides the canonical values for that tool — the tool-specific value takes precedence, and the section itself is not emitted (except `name`, which always comes from the file name). On import, `severity-default` maps back to the generic `severity` field, and the `name` field is dropped because it is re-derived from the file name on the next generate.\n\n> **v1 limitation:** Amp also discovers subtree-scoped checks (e.g. `api/.agents/checks/`), but rulesync sources carry no directory-placement semantics, so those subtree-scoped checks are not generated. See the [Amp manual](https://ampcode.com/manual).\n\n## `.rulesync/skills/*/SKILL.md`\n\nExample:\n\n```md\n---\nname: example-skill # skill name\ndescription: >- # skill description\n A sample skill that demonstrates the skill format\ntargets: ["*"] # * = all, or specific tools\n# (optional) shared default for tools that support the flag — claudecode, cursor,\n# zed, pi, qwencode, grokcli, and factorydroid. Any of those tool sections can\n# override it by setting their own `disable-model-invocation` value below.\ndisable-model-invocation: true\n# (optional) shared default for tools that support the flag — claudecode, qwencode,\n# vibe, grokcli, and factorydroid. Any of those tool sections can override it by\n# setting their own `user-invocable` value below.\nuser-invocable: false\nclaudecode: # for claudecode-specific parameters\n model: sonnet # opus, sonnet, haiku, or any string\n when_to_use: When the user asks to review a PR # (optional) extra trigger context appended to description\n allowed-tools: # (optional) tools usable without asking; accepts a string or a list\n - "Bash"\n - "Read"\n - "Write"\n - "Grep"\n disallowed-tools: # (optional) removes these tools while the skill is active (string or list)\n - "WebFetch"\n effort: high # (optional) effort while active: low | medium | high | xhigh | max\n argument-hint: "[pr-number]" # (optional) autocomplete hint for expected arguments\n arguments: # (optional) named positional arguments for $name substitution (string or list)\n - "pr_number"\n context: fork # (optional) set to "fork" to run the skill in a forked subagent context\n agent: code-reviewer # (optional) subagent type to use when context: fork\n background: false # (optional, context: fork only) wait for the forked subagent in the invoking turn instead of backgrounding it (default true)\n shell: bash # (optional) shell for ! command blocks: bash (default) or powershell\n hooks: # (optional) hooks scoped to the skill\'s lifecycle (free-form per the Claude Code docs)\n PreToolUse:\n - matcher: "Bash"\n disable-model-invocation: true # (optional) disable model invocation for this skill\n user-invocable: false # (optional) hide from the / menu while keeping model access\n scheduled-task: true # (optional) emit to .claude/scheduled-tasks//SKILL.md instead of .claude/skills//SKILL.md\n # paths (optional) limits auto-activation to matching globs. Accepts a\n # comma-separated string, e.g. paths: "src/**/*.ts,test/**/*.ts", or a list:\n paths:\n - "src/**/*.ts"\n - "test/**/*.ts"\ncodexcli: # for codexcli-specific parameters\n short-description: A brief user-facing description\n # The following sections are emitted to the agents/openai.yaml sidecar next to SKILL.md.\n # See https://developers.openai.com/codex/skills.md\n interface: # (optional) UI metadata\n display_name: Example Skill\n short_description: A brief user-facing description\n default_prompt: Do the thing\n policy: # (optional) invocation policy\n allow_implicit_invocation: false # only invoke explicitly via $skill\n dependencies: # (optional) tool dependencies\n tools:\n - type: mcp\n value: example\n description: Example MCP tool\npi: # for Pi Coding Agent-specific parameters (optional; Agent Skills standard)\n # Authored either as a canonical list or as the spec\'s space-delimited string;\n # emitted to SKILL.md as the string, and imported back as the list.\n allowed-tools:\n - "Bash"\n - "Read"\n disable-model-invocation: true # (optional) disable model invocation for this skill\n license: MIT # (optional)\n compatibility: "Requires git and jq" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n metadata: # (optional) free-form metadata\n author: rulesync\nreplit: # for Replit Agent-specific parameters (optional; Agent Skills standard)\n # Authored either as a canonical list or as the spec\'s space-separated string;\n # emitted to SKILL.md as the string, and imported back as the list.\n allowed-tools:\n - "Bash"\n - "Read"\n license: MIT # (optional)\n compatibility: "Requires git and docker" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n metadata: # (optional) free-form metadata\n author: rulesync\ndeepagents: # for deepagents-cli (dcode)-specific parameters (optional; Agent Skills standard)\n # Authored as a canonical list; emitted to SKILL.md as a space-delimited string\n # (e.g. "Bash Read") because dcode rejects a YAML list at runtime.\n allowed-tools:\n - "Bash"\n - "Read"\n license: MIT # (optional)\n compatibility: # (optional) free-form compatibility metadata\n deepagents-version: ">=0.1.0"\n metadata: # (optional) free-form metadata\n author: rulesync\nopencode: # for OpenCode-specific parameters (optional)\n license: MIT # (optional)\n compatibility: # (optional) free-form compatibility metadata\n opencode-version: ">=1.16.0"\n metadata: # (optional) free-form metadata\n author: rulesync\n allowed-tools: # (optional) Anthropic-spec passthrough; OpenCode ignores unknown fields\n - "Bash"\n - "Read"\nkilo: # for Kilo Code-specific parameters (optional)\n license: MIT # (optional)\n compatibility: # (optional) free-form compatibility metadata\n kilo-version: ">=7.0.0"\n metadata: # (optional) free-form metadata\n author: rulesync\n allowed-tools: # (optional) backward-compat passthrough; not part of Kilo\'s official SKILL.md frontmatter\n - "Bash"\n - "Read"\nkimi-code: # for Kimi Code-specific parameters (optional; project/global .kimi-code/skills/)\n type: inline # (optional) prompt, inline, or flow\n whenToUse: "When reviewing pull requests" # (optional) model invocation hint\n disableModelInvocation: false # (optional) prevent automatic model invocation\n arguments: ["pull_request"] # (optional) named arguments, also accepts a whitespace-separated string\nagentsskills: # for the Agent Skills standard target (optional; supports project + global ~/.agents/skills/)\n license: MIT # (optional)\n compatibility: "Requires Python 3.14+ and uv" # (optional) free-form string, 1–500 chars (an object is also accepted for back-compat)\n metadata: # (optional) free-form metadata (spec-recommended place for skill versioning)\n version: "1.0.0"\n allowed-tools: "shell" # (optional, experimental) space-separated string or list\ncopilot: # for GitHub Copilot-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n license: MIT # (optional)\n allowed-tools: "shell" # (optional) tools pre-approved without per-use confirmation\ncopilotcli: # for GitHub Copilot CLI-specific parameters (optional; project .github/skills/, global ~/.copilot/skills/)\n license: MIT # (optional)\n allowed-tools: "shell" # (optional) tools pre-approved without per-use confirmation\n argument-hint: "[message]" # (optional) hint shown for the skill\'s expected arguments\n user-invocable: true # (optional, default true) whether users can run it with /SKILL-NAME\n disable-model-invocation: false # (optional, default false) stop the agent from invoking it on its own\nrovodev: # for Rovo Dev CLI-specific parameters (optional; Agent Skills standard)\n allowed-tools: "grep bash" # (optional) space-separated string (a YAML list is also accepted)\n license: MIT # (optional)\n compatibility: "Requires Python 3.14+ and uv" # (optional) free-form string (object form also accepted)\n metadata: # (optional) free-form metadata\n author: rulesync\nzed: # for Zed-specific parameters (optional)\n disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\ncursor: # for Cursor-specific parameters (optional)\n paths: # (optional) glob patterns (string or list) scoping the skill to matching files\n - "src/**/*.ts"\n disable-model-invocation: true # (optional) only include the skill when invoked via /skill-name\n metadata: # (optional) free-form metadata\n author: rulesync\nfactorydroid: # for Factory Droid-specific parameters (optional)\n disable-model-invocation: true # (optional) prevent the model from auto-invoking this skill\n user-invocable: false # (optional) hide from the slash-command menu, keep model access\ntakt: # takt specific parameters (optional; emitted under .takt/facets/knowledge/ — frontmatter is dropped on emit)\n name: "renamed-stem" # (optional) override the emitted filename stem (no path separators or "..")\n extends: "base" # (optional) emit a leading `{extends:}` facet-inheritance directive (Takt 0.39.0+)\ndevin: # for Devin-specific parameters (optional; project .devin/skills/, global ~/.config/devin/skills/)\n argument-hint: "[environment]" # (optional) hint shown after the slash-command name\n model: "fast" # (optional) model override while the skill runs\n subagent: true # (optional) run the skill in a subagent (string or boolean per Devin\'s docs)\n agent: "deployer" # (optional) named agent profile to run the skill with\n allowed-tools: # (optional) tools available while the skill runs (string or list)\n - "Bash(git status:*)"\n permissions: {} # (optional) auto-approval rules applied while the skill runs (load-bearing since Devin CLI v3000.1.23)\n triggers: ["user"] # (optional) invocation gating; omitted = user + model. The shared disable-model-invocation / user-invocable flags map onto this when unset.\nqwencode: # for Qwen Code-specific parameters (optional; project .qwen/skills/, global ~/.qwen/skills/)\n priority: 10 # (optional) higher values appear earlier in /skills listings\n paths: # (optional) glob patterns gating model discovery to matching files (a scalar is coerced to the array Qwen Code requires)\n - "src/**/*.ts"\n user-invocable: false # (optional) hide from slash-command invocation, keep model access\n disable-model-invocation: true # (optional) hide from the model but allow direct user invocation\n allowedTools: # (optional) permissions.allow-syntax rules auto-approved while the skill is active\n - "Shell(git status:*)"\n model: "fast" # (optional) model override while the skill runs (model id, fast, authType:modelId, inherit)\n hooks: {} # (optional) session-scoped hooks registered while the skill runs (settings.json shape)\n when_to_use: "Use when deploying" # (optional) invocation guidance surfaced in the SkillTool description\n argument-hint: "[environment]" # (optional) hint shown after the slash-command name in completion\ngrokcli: # for Grok CLI-specific parameters (optional)\n user-invocable: false # (optional) hide from the skill tool, keep model access\n disable-model-invocation: true # (optional) block auto-invocation, keep the slash command\nvibe: # for Vibe Code-specific parameters (optional)\n user-invocable: false # (optional) hide from slash-command invocation, keep model access\n allowed-tools: "Bash Read" # (optional) space-delimited or list of allowed tool names\n---\n\nThis is the skill body content.\n\nYou can provide instructions, context, or any information that helps the AI agent understand and execute this skill effectively.\n\nThe skill can include:\n\n- Step-by-step instructions\n- Code examples\n- Best practices\n- Any relevant context\n\nSkills are directory-based and can include additional files alongside SKILL.md.\n\nWhen `claudecode.scheduled-task: true` is set, that skill is emitted only as a Claude Code scheduled task and is not emitted to other tools even if `targets` contains `"*"`.\n```\n\n> **`.agents/skills/` ownership note:** `.agents/skills/` is not an AGENTS.md convention — the AGENTS.md standard defines only `AGENTS.md` itself. It is the [Agent Skills](https://agentskills.io/specification) project location, which the native `agentsskills` target writes. Several targets write there — `agentsskills`, `agentsmd`, `aiassistant`, `codexcli`, `amp`, `zed`, `replit` and both Antigravity targets — because they all implement the same convention. Each native target writes its own documented frontmatter, so enabling more than one and reordering `--targets` can change which optional keys end up in the file; that is inherent to several tools sharing one path and is not specific to any of them.\n\n> The **simulated** `agentsmd` writer is the exception that is fixed: it has no frontmatter model of its own (the AGENTS.md standard defines no skills at all), so it used to overwrite the native output with a bare `name`/`description` pair and silently drop `license`, `compatibility`, `metadata` and `allowed-tools`. It now emits exactly what `agentsskills` emits, so a simulated writer can never degrade the file a native target owns.\n\n> **Claude Code nested skills note:** Claude Code v2.1.178+ also loads skills from **nested** `.claude/skills/` directories below the working directory (a skill in `apps/web/.claude/skills/` becomes available when working on files there, and a name clash with a root skill keeps both under a directory-qualified name like `apps/web:deploy`). `rulesync import --targets claudecode --features skills` discovers those nested directories (import-only, lenient, same dependency/build-directory exclusions as the nested `AGENTS.md` scan; symlinks not followed) so an existing nested skill is no longer invisible. On a name clash the root skill wins the import — rulesync\'s flat skill namespace cannot express the qualified variant. Generation stays targeted at the project-root `.claude/skills/`; to scope a skill\'s _activation_ to a subtree, use the `paths` frontmatter, or run a separate generate with `--output-roots ` for physical co-location.\n\n> **Note:** `claudecode.disallowed-tools` (a space/comma-separated string or a YAML list) removes the listed tools from the model while the skill is active. The same field is available on Claude Code slash commands. Both round-trip through the `claudecode` frontmatter section.\n\n> **Note:** Codex CLI reads UI metadata, invocation policy, and tool dependencies from an `agents/openai.yaml` sidecar next to `SKILL.md` (Codex\'s `SKILL.md` frontmatter only carries `name` and `description`). When `codexcli.interface`, `codexcli.policy`, or `codexcli.dependencies` is present, Rulesync emits `.agents/skills//agents/openai.yaml` and reads it back on import. If the sidecar is emitted and `interface.short_description` is absent, the legacy `codexcli.short-description` is routed there. See the [Codex skills docs](https://developers.openai.com/codex/skills.md).\n\n> **Reasonix note:** Reasonix discovers Anthropic-style directory-layout skills (`/SKILL.md`) under `.reasonix/skills/` (project) / `~/.reasonix/skills/` (global, via `--global`). Rulesync emits the portable `name`/`description` frontmatter (Reasonix supports additional optional keys, but only that pair is modeled); the schema is loose, so any extra keys on an imported `SKILL.md` survive the round-trip. See the [Reasonix GUIDE](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md).\n\n> **Hermes Agent note:** Hermes skills are global-only under `~/.hermes/skills//SKILL.md`. Standard Agent Skills fields (`license`, `compatibility`, and `allowed-tools`) round-trip through `agentsskills` and are normalized to the Agent Skills spec shapes described above (so `allowed-tools` is written and imported the same way as for `agentsskills`); Hermes-native fields such as `version`, `author`, `platforms`, `environments`, `required_environment_variables`, `required_credential_files`, and `metadata.hermes` round-trip through `hermesagent`. Canonical `name` and `description` always own those two frontmatter keys.\n\n> **Kimi Code note:** Kimi Code discovers skills under `.kimi-code/skills/` (project) and `~/.kimi-code/skills/` (global), plus the shared `.agents/skills/` root at either scope. Rulesync generates the recommended directory layout (`/SKILL.md`) and imports both that layout and flat `.md` skills; for flat files, a missing `name` comes from the filename and a missing `description` falls back to the first non-empty body line (up to 240 characters), matching Kimi. Imported skills are written to `.rulesync/skills//SKILL.md`, using the normalized logical frontmatter name rather than the source directory or filename. Duplicate precedence follows Kimi\'s case-insensitive logical frontmatter `name`: the Kimi-specific root takes precedence over `.agents/skills/`, and a directory skill takes precedence over a same-named flat file within one root. Shared roots are import-only and are never removed by Kimi-target orphan deletion. Besides `name`/`description`, Rulesync maps Kimi\'s `type`, `whenToUse`, `disableModelInvocation`, and `arguments` frontmatter through the `kimi-code:` block and preserves supporting files beside directory-layout `SKILL.md`. The shared top-level `disable-model-invocation` value supplies the Kimi flag unless the tool-specific block overrides it. See the [Kimi Code Agent Skills docs](https://moonshotai.github.io/kimi-code/en/customization/skills.html).\n\n## `.rulesync/mcp.jsonc`\n\n`.rulesync/mcp.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/mcp.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nExample:\n\n```json\n{\n "mcpServers": {\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json",\n "serena": {\n "description": "Code analysis and semantic search MCP server",\n "type": "stdio",\n "command": "uvx",\n "args": [\n "--from",\n "git+https://github.com/oraios/serena",\n "serena",\n "start-mcp-server",\n "--context",\n "ide-assistant",\n "--enable-web-dashboard",\n "false",\n "--project",\n "."\n ],\n "env": {}\n },\n "context7": {\n "description": "Library documentation search server",\n "type": "stdio",\n "command": "npx",\n "args": ["-y", "@upstash/context7-mcp"],\n "env": {}\n }\n }\n}\n```\n\n### Tool-scoped server blocks (`{toolname}.mcpServers`)\n\nServers under the shared `mcpServers` key are emitted to every targeted tool. To scope a server to a single tool, add a tool-scoped `{toolname}` block alongside it — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.permission` in `.rulesync/permissions.jsonc`:\n\n```jsonc\n{\n "mcpServers": {\n "shared-server": { "type": "stdio", "command": "echo" },\n },\n "claudecode": {\n "mcpServers": {\n // Added only to Claude Code\'s MCP config.\n "claude-only-server": { "type": "http", "url": "https://example.com/mcp" },\n // `null` removes a shared server for Claude Code only.\n "shared-server": null,\n },\n },\n}\n```\n\n- A tool-scoped entry with the same name as a shared server **replaces it wholesale** for that tool (no field-level merge).\n- A tool-scoped entry set to `null` **removes** the shared server for that tool.\n- Any MCP-capable `--targets` name is accepted as a block key (`claudecode`, `cursor`, `codexcli`, ...). Targets that share one output file resolve identically so the shared file never depends on generation order: the deprecated `claudecode-legacy` target reads the `claudecode` block; the `kiro-cli` / `kiro-ide` targets read the `kiro` block (all three write the same `.kiro/settings/mcp.json`); and the `antigravity-ide` / `antigravity-cli` targets both apply both `antigravity-*` blocks in a fixed order (`antigravity-ide` first, then `antigravity-cli` — the CLI block wins per server) because they share their output file at both scopes (`.agents/mcp_config.json` in project mode, `~/.gemini/config/mcp_config.json` in global mode).\n\n> **Generation filter: per-server `enabled`.** Set `"enabled": false` on a server (in the shared map or a tool-scoped block) to keep the definition in the source file while emitting it to **no** tool config at all — a temporary off switch that does not lose the entry. Omitted means enabled, so existing configs keep generating everything; writing `"enabled": true` is opt-in clarity. This is distinct from the canonical `disabled`, which is a **pass-through** field the tools read (written as `disabled: true`, or translated to each tool\'s own spelling): `enabled: false` wins and drops the server entirely, while `disabled` only matters for servers still emitted. The field is rulesync-source-only and never reaches generated output — several tools (OpenCode, Kilo, Grok CLI, Goose) have a native `enabled` field with different semantics — and import never invents it: a tool\'s native enabled/disabled state keeps mapping to the canonical `disabled` (though a stray hand-written `enabled` in a passthrough-imported tool file does come back as the canonical filter). Two edges to know: a tool-scoped entry **replaces the shared entry wholesale**, so a same-named tool-scoped entry without `enabled: false` re-emits the server for that tool (per-tool re-enabling); and on merge-style shared configs (e.g. Hermes Agent\'s `config.yaml`), disabling a previously generated server stops writing it but does not remove the already-written entry — same as deleting the definition.\n\n> **Deprecated: per-server `targets`.** The older per-server `"targets": ["tool", ...]` array is still honored as a filter (a missing value or `["*"]` means every tool), but it is deprecated and logs a warning at generate time. Migrate by moving the server into the matching `{toolname}.mcpServers` block(s).\n\n> **JetBrains AI Assistant note:** Rulesync writes the native `{ "mcpServers": { ... } }` configuration to `.ai/mcp/mcp.json` in project mode and `~/.ai/mcp/mcp.json` in global mode. Both scopes support STDIO and remote server entries using the shape documented in [JetBrains AI Assistant\'s MCP guide](https://www.jetbrains.com/help/ai-assistant/mcp.html).\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/mcp.jsonc`:\n\n```json\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json",\n "mcpServers": {}\n}\n```\n\n### Transport types (`type` / `transport`)\n\nThe `type` (and the equivalent `transport`) field accepts `local`, `stdio`, `sse`, `http`, `ws`, and `streamable-http`. `streamable-http` is the MCP specification\'s name for the HTTP transport and is accepted as an alias of `http`, so configurations copied from a server\'s documentation work unchanged. `ws` is the WebSocket transport (a persistent bidirectional connection) and accepts the same `url`/`headers`/`headersHelper`/`timeout` fields as `http`. Tools that do not recognize a given transport keep it on round-trip but may ignore it at runtime.\n\n> **OpenCode skills note:** on import, Rulesync also reads the `skills.paths` array of `opencode.json` / `opencode.jsonc` ("Additional paths to skill folders") and scans each entry as an extra skill root, so skills a project keeps outside `.opencode/skills/` are no longer invisible to `rulesync import`. These roots are import-only — generation keeps writing to Rulesync\'s own managed root — and a skill of the same name found in a managed root still wins. Each entry is resolved against the directory the config was read from — the project root in project mode, `~/.config/opencode/` in global mode — which is what OpenCode itself does. An absolute path, or one that escapes that directory, is ignored, and a directory under a configured root that is not a skill is skipped with a warning rather than failing the run, since a configured root is arbitrary user territory. `skills.urls` is a remote-fetch surface and is out of scope for a file-based generator.\n\n> **Kilo Code note:** Kilo\'s MCP config uses its own native shape in `kilo.jsonc` (`type: "local" | "remote"`, `environment`, `enabled`, `command` as an array). Rulesync maps `stdio`/`local` ⇄ Kilo `local` and `http`/`sse` ⇄ Kilo `remote`; on import, Kilo `remote` is normalized to the canonical `http` transport (the deprecated `sse` is no longer emitted). The Kilo-specific `timeout` (local + remote, a positive integer in milliseconds) and `oauth` (remote only — either an OAuth-config object or `false` to disable auto-detection) fields are preserved on round-trip. The `kilo.jsonc` `skills` config key (`skills.paths` for extra skill locations and `skills.urls` for remote skill manifests) is likewise preserved when Rulesync writes the file. A bare `{"enabled": false}` entry — Kilo\'s way of switching off a server another config layer defines, such as the global config or a marketplace — round-trips as itself: it imports as a canonical server carrying only `disabled: true`/`disabled: false` and no transport, and a server in that shape is written back as `{"enabled": …}` rather than as a local server with an empty command it cannot start. The enabled state has to be stated outright in both directions: for a transport-less server that says nothing about `disabled`, a toggle already in `kilo.jsonc` is left exactly as it is, and if there is none the server is skipped with a warning — a toggle overrides the layer that defines the server, so writing `enabled: true` for it would switch back on what you turned off there. Kilo\'s per-tool `enabledTools`/`disabledTools` reach the generated file at all now — they used to be stripped before this adapter saw them, so a filter read out of `kilo.jsonc` was deleted from it on the next generate. A skipped server\'s filters are written to the `tools` map either way, since that map is keyed by server name and reaches servers `mcp` does not list; on import, a `tools` entry naming no listed server comes back as a server carrying nothing but the filters, so it survives the round-trip. A server with no transport — a toggle, or one of those filter-only entries — is imported into the tool-scoped `kilo.mcpServers` block rather than the shared `mcpServers` map, because an entry with no command and no url is a server the other tools\' configs cannot start. All of this applies equally to OpenCode: its published schema carries the same bare-toggle union member, it round-trips a toggle as itself under the same explicit-state rule, its `tools` map works the same way, and its transport-less servers land in `opencode.mcpServers`. The entry must carry no field of a local or remote server (`type`, `command`, `url`, `headers`, `environment`, `cwd`, `timeout`, `oauth`); an entry that is malformed in some other way still fails loudly rather than being quietly read as a toggle and written back with its command, headers, or OAuth secrets gone, while an unrelated key Kilo adds later is accepted rather than failing the run (it is not carried across the round-trip, though — a toggle imports as its enabled state and nothing else). Since a toggle keeps nothing but its enabled state, a canonical server that declares no transport but still carries fields such as `args` or `env` is written as a toggle with those fields dropped and a warning naming them. A server that names a transport it cannot reach — a `type` with no `command`, an `http` with no `url` — is skipped with a warning instead, because `{"type": "local", "command": []}` is a server Kilo cannot start. An existing `kilo.jsonc` carrying that shape (earlier Rulesync versions wrote it) imports as a server with no transport rather than failing the run. The same applies to OpenCode, whose config uses the same shape. Rejecting it used to fail the whole `--targets kilo` run rather than the MCP feature alone, because `kilo.jsonc` is the file the rules feature writes too.\n\n> **Zed note:** Zed configures MCP servers under `context_servers` in its shared settings file (`.zed/settings.json` project, `~/.config/zed/settings.json` global — `%APPDATA%\\Zed\\settings.json` on Windows), whose value is an untagged shape with no `type` field: a stdio server is `{"command": , "args", "env", "timeout"}`, a remote one `{"url", "headers", "timeout"}`, and an extension-provided one neither. Rulesync translates the canonical fields into those shapes instead of forwarding them verbatim (which used to hand Zed keys it silently ignores — most seriously `disabled: true`, which left the server **enabled**): `disabled: true` becomes `enabled: false` (and imports back as `disabled: true`), the `httpUrl` alias is normalized to `url`, an array `command` is flattened to Zed\'s single command string with the rest prepended to `args`, and canonical-only fields (`type`/`transport`, `alwaysAllow`, `trust`, `cwd`, `networkTimeout`, the Kiro lists) are dropped. Fields rulesync does not model — a remote server\'s `oauth` block, an extension server\'s `settings` — pass through untouched, so they are best authored in the tool-scoped `zed.mcpServers` block. A server Zed cannot start is skipped with a warning rather than written broken: an `sse` or `ws` server (Zed has neither transport), a remote server with no `url`, a local one with no `command`. A server with no transport at all is written as Zed\'s extension-provided variant, and on import such an entry lands in the tool-scoped `zed.mcpServers` block rather than the shared `mcpServers` map, since other tools cannot start it.\n\n> **Kimi Code note:** MCP servers are written to `.kimi-code/mcp.json` (project) and `~/.kimi-code/mcp.json` (global). Kimi Code supports stdio, HTTP, and SSE plus `env`, `cwd`, `headers`, `bearerTokenEnvVar`, `enabled`, `startupTimeoutMs`, `toolTimeoutMs`, `enabledTools`, and `disabledTools`; Rulesync preserves the canonical fields that Kimi accepts. Canonical `local` maps to stdio and `streamable-http` maps to HTTP. WebSocket servers are skipped with a warning because Kimi has no WebSocket transport. A `kimi-code` block may also carry `startupTimeoutMs` / `toolTimeoutMs`, which are **not** per-server: they become Kimi\'s `[mcp] startup_timeout_ms` / `tool_timeout_ms` defaults in the shared global `~/.kimi-code/config.toml`, applying to every MCP server including ones Rulesync did not write (a per-server value in `mcp.json` still wins). Global scope only, since `config.toml` has no project counterpart, and merged in place so the `hooks` and `permission` sections of the same file survive. The merge is per key: authoring only one of the two timeouts leaves a hand-written sibling alone, and dropping the override entirely leaves the section as it stands rather than deleting it — remove the keys from `config.toml` by hand if you want them gone. See the [Kimi Code MCP docs](https://moonshotai.github.io/kimi-code/en/customization/mcp.html) and [config-files reference](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html#mcp).\n\n> **Hermes Agent note:** Hermes MCP servers live under `mcp_servers` in the shared `~/.hermes/config.yaml`. Rulesync preserves OAuth fields (`redirect_uri`, `redirect_host`, `redirect_port`, `client_id`, `client_secret`, and `scopes`) plus `idle_timeout_seconds`, `max_lifetime_seconds`, `ssl_verify` (`true`/`false` or a PEM CA-bundle path), `skip_preflight`, and the `sampling` mapping (carried as an opaque object so new sub-keys keep working). On import, portable server fields remain in shared `mcpServers`; Hermes-only fields are isolated in the full `hermesagent.mcpServers.` replacement block so they cannot leak to other targets.\n\n> **Devin note:** Since Devin v3000.3 (the Local 3.6 release), MCP servers live in a dedicated `mcpServers`-keyed file: `.devin/mcp_config.json` (project) and `~/.config/devin/mcp_config.json` (global, via `--global`). The file is MCP-only and rulesync-owned (rewritten whole, deletable), unlike the shared `.devin/config.json` that permissions and hooks keep patching in place. Rulesync no longer writes the legacy `config.json` `mcpServers` key — Devin auto-migrates it away on startup, so re-seeding it would fight the migration — but import still falls back to that key when no `mcp_config.json` exists, so pre-v3000.3 repos migrate cleanly. The gitignored personal override `.devin/mcp_config.local.json` is never read or written (it is covered by the derived `.gitignore`). See the [Devin MCP configuration docs](https://docs.devin.ai/cli/extensibility/mcp/configuration).\n\n> **Warp note:** Warp reads file-based MCP servers from `.warp/.mcp.json` (project) and `~/.warp/.mcp.json` (global). Warp spells the working directory `working_directory` (used for resolving relative paths), so the canonical `cwd` is translated to it on generate and back on import; a tool-native `working_directory` already on the server wins over `cwd`. See the [Warp MCP docs](https://docs.warp.dev/agent-platform/capabilities/mcp/).\n\n> **Takt note (partial / transport-allowlist only):** Takt does **not** have a project- or global-level registry of MCP server _definitions_. The concrete `mcp_servers` map (`command`/`args`/`env` or `type`/`url`/`headers`) is declared **per workflow step** inside individual workflow YAML files; there is no top-level `mcp_servers` key in `config.yaml`, and Takt\'s config loader hard-rejects unknown top-level keys (introduced with MCP support in [Takt v0.21.0](https://github.com/nrslib/takt/blob/main/CHANGELOG.md)). What `config.yaml` _does_ hold is the **default-deny transport allowlist** `workflow_mcp_servers: { stdio, sse, http }` — without it, workflow-defined MCP servers are refused regardless of how they are declared. So Rulesync emits **only** this allowlist into the shared `.takt/config.yaml` (project) / `~/.takt/config.yaml` (global), enabling exactly the transports your `.rulesync/mcp.jsonc` servers use (`local`/`stdio` ⇒ `stdio`; `sse` ⇒ `sse`; `http`/`streamable-http`/`ws` ⇒ `http`). The merge is in place — every other top-level key (`provider`, `provider_profiles`, …) is preserved and the file is never deleted. **Documented lossiness:** per-server names, commands, env, URLs, and headers are not representable in `config.yaml` and are intentionally **not** written; you still declare the concrete servers in your workflow YAML steps, and Rulesync only opens the transport gate that permits them. As a corollary, **import** cannot reconstruct server definitions from a transport allowlist and yields an empty `mcpServers` map. See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\n### MCP Tool Config (`enabledTools` / `disabledTools`)\n\nYou can control which individual tools from an MCP server are enabled or disabled using `enabledTools` and `disabledTools` arrays per server.\n\n```json\n{\n "mcpServers": {\n "serena": {\n "type": "stdio",\n "command": "uvx",\n "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"],\n "enabledTools": ["search_symbols", "find_references"],\n "disabledTools": ["rename_symbol"]\n }\n }\n}\n```\n\n- `enabledTools`: An array of tool names that should be explicitly enabled for this server.\n- `disabledTools`: An array of tool names that should be explicitly disabled for this server.\n\n> **Kiro note:** Kiro MCP servers are written under `mcpServers` in `.kiro/settings/mcp.json` (project) and `~/.kiro/settings/mcp.json` (global). Kiro supports `disabledTools` natively and Rulesync preserves it on generate and import. Kiro does not expose a corresponding per-server `enabledTools` allowlist, so that field is omitted for Kiro targets.\n\n> **Qwen Code note:** MCP servers are written to the `mcpServers` key of `.qwen/settings.json` (project) / `~/.qwen/settings.json` (global, via `--global`). Qwen supports stdio (`command`/`args`), SSE (`url`), and HTTP (`httpUrl`) transports. Rulesync maps the canonical per-server `enabledTools` ⇄ Qwen\'s `includeTools` (allowlist) and `disabledTools` ⇄ Qwen\'s `excludeTools` (denylist). Other top-level keys in `settings.json` are preserved on round-trip.\n\n> **Codex CLI server-name note:** Codex requires MCP server names matching `[a-zA-Z0-9_-]+`, so Rulesync auto-normalizes non-conforming names on generate (lowercase, runs of other characters become `_`, leading/trailing `_` trimmed) — e.g. `Postgres MCP - Production - Read Only` becomes `postgres_mcp_production_read_only`. If two names normalize to the same Codex name, the last processed server overwrites the earlier one (with a warning). A name with no representable characters at all (e.g. a fully Japanese name) falls back to a stable hash-derived name like `mcp_1a2b3c4d` instead of being dropped; rename the server in `.rulesync/mcp.jsonc` to pick a readable Codex name. This normalization is one-way: importing back from the generated `config.toml` yields the normalized name, not the original.\n\n### Codex-specific: pass shell env vars to MCP servers (`envVars`)\n\nCodex CLI supports a per-server array of shell env var names to inherit when launching the MCP server process. The source schema uses `envVars` (camelCase, matching the project convention used by sibling fields like `enabledTools`/`disabledTools`); the codex generator renames it to `env_vars` (snake_case) for codex\'s native `config.toml` format.\n\nThis is distinct from `env` (which is a literal `{name: value}` map) — `envVars` is a list of names whose **values come from the user\'s environment at runtime**. Both fields may coexist on the same server.\n\n```json\n{\n "mcpServers": {\n "pal": {\n "type": "stdio",\n "command": "uvx",\n "args": [\n "--from",\n "git+https://github.com/BeehiveInnovations/pal-mcp-server.git",\n "pal-mcp-server"\n ],\n "envVars": ["OPENAI_API_KEY", "OPENROUTER_API_KEY", "GEMINI_API_KEY"]\n }\n }\n}\n```\n\nGenerated `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.pal]\ntype = "stdio"\ncommand = "uvx"\nargs = ["--from", "git+https://github.com/BeehiveInnovations/pal-mcp-server.git", "pal-mcp-server"]\nenv_vars = ["OPENAI_API_KEY", "OPENROUTER_API_KEY", "GEMINI_API_KEY"]\n```\n\nAn entry may also be an object naming the environment to read the variable from: `{ "name": "REMOTE_TOKEN", "source": "remote" }` reads it from the remote executor environment (and requires remote MCP stdio support), while a bare name and `"source": "local"` read from Codex\'s own environment. The object form is written to `config.toml` as an inline table, matching Codex\'s documented shape. Only `name` and `source` are accepted in that object — Codex rejects an unknown key there, and rejecting one server\'s entry would take the whole `config.toml` down with it, so Rulesync fails on the canonical file instead. For the same reason an entry that a `config.toml` already holds in some other shape is dropped with a warning on import rather than written into a `.rulesync/mcp.jsonc` the next generate would refuse.\n\n- Emitted only into the codex CLI output. Stripped from `RulesyncMcp.getMcpServers()` so it does not appear in other tools\' generated configs (Claude Code, Kilo, OpenCode, Gemini CLI, Cursor, Cline, Junie, Factorydroid, Rovodev, etc.).\n- Use this for secrets and API keys you do not want literal-encoded into a committed `mcp.json`.\n- Precedence: codex CLI resolves these names from the user\'s runtime shell environment. If a name is also set in `env` (literal value), the codex CLI behavior is upstream-defined; see the [Codex configuration reference](https://developers.openai.com/codex/config-reference#mcp_serversid-env_vars) (last checked 2026-05-13) for the exact resolution rule.\n\n### Codex-specific: run a stdio server remotely (`experimentalEnvironment`)\n\nFor stdio servers, `experimentalEnvironment: "remote"` starts the server through a remote executor environment when one is available. It is written as `experimental_environment` in `config.toml`. Like `envVars`, it is stripped before every other tool\'s MCP config is written, so it cannot leak into a config that would not understand it — and for the same reason, a server config copied straight out of a `config.toml` may spell it `experimental_environment`, which is accepted and normalized on the way to Codex.\n\nSee the [Codex MCP reference](https://learn.chatgpt.com/docs/extend/mcp) for both fields.\n\n#### Codex-specific: OAuth client id (`oauth.clientId` → `client_id`)\n\nA server\'s `oauth` block is preserved in the canonical Claude Code shape (camelCase `clientId`), but Codex CLI reads the OAuth client id from snake_case `oauth.client_id`. Without it, `codex mcp login ` falls back to dynamic client registration and fails for providers that do not support it (e.g. Slack). The codex generator therefore **duplicates** `clientId` into a sibling `client_id`, keeping the camelCase key so tools that expect it keep working:\n\n```toml\n[mcp_servers.slack.oauth]\nclientId = "1601185624273.8899143856786"\nclient_id = "1601185624273.8899143856786"\ncallbackPort = 3118\n```\n\nOnly a string `clientId` is duplicated (a non-string value would not be a usable OAuth client id), and an explicit `client_id` already present in the source is left untouched. On import, `client_id` collapses back to the canonical `clientId` (and is dropped when both are present) so the round-trip stays stable.\n\n> **Grok CLI note:** MCP servers are written to a `[mcp_servers.]` table in `.grok/config.toml` (project) / `~/.grok/config.toml` (global, via `--global`). The file is treated as shared Grok config: Rulesync only replaces the `mcp_servers` key and preserves every other table on round-trip, and it is never deleted. Unlike Codex CLI, Grok uses a literal `env` table (it does not support the `env_vars` runtime-passthrough list) and has no per-server tool allow/deny lists, so the only field rename is `disabled` (rulesync) ⇄ `enabled = false` (grok); an active server simply omits `enabled`. Servers with no environment variables are emitted without a dangling `[mcp_servers..env]` table (empty nested tables are stripped), and a server whose entire configuration would be empty is dropped with a warning.\n\n### Goose-specific: MCP servers as `extensions` (global) and open-plugin manifest (project)\n\nGoose configures MCP servers in two locations depending on scope:\n\n- **Global (`--global`):** MCP servers are written as **extensions** in the shared user config `~/.config/goose/config.yaml`. The schema is non-standard, so Rulesync maps canonical MCP fields to Goose\'s: `command` → `cmd` (an array `command` folds its tail into `args`), `env` → `envs`, `url`/`httpUrl` → `uri`, and `disabled: true` → `enabled: false`. The `type` is derived — `command` ⇒ `stdio`, a remote `url` ⇒ `streamable_http` (or `sse` when the canonical `type` is `sse`). Each extension also carries its own `name`. Generation merges the `extensions:` block into the existing `config.yaml`, preserving other Goose settings (model, provider, ...), and the file is never deleted. This location supports **both stdio and remote** (http/sse) servers.\n- **Project:** Goose v1.39.0+ discovers MCP extensions in **open plugins** at `/.agents/plugins//.mcp.json` (and `~/.agents/plugins//.mcp.json` at user scope). Rulesync emits `.agents/plugins/rulesync/.mcp.json`, reusing the same `.agents/plugins/rulesync/` tree already used for Goose hooks. The manifest uses the **Claude-style** `{ "mcpServers": { "": { "command", "args", "env", "cwd" } } }` shape. This manifest is **stdio-only** — it cannot express `url`/`headers`, so **remote (http/sse) servers are skipped with a warning** in project mode; sync them with `--global` to `~/.config/goose/config.yaml` instead. The `.mcp.json` manifest is owned by Rulesync and is deleted when no servers remain.\n\nSee the [Goose extensions docs](https://block.github.io/goose/docs/getting-started/using-extensions/) and [open-plugins MCP PR #9471](https://github.com/block/goose/pull/9471).\n\n### Goose-specific: commands as recipes, subagents as custom agents\n\nGoose [recipes](https://block.github.io/goose/docs/guides/recipes/recipe-reference/) are reusable YAML workflow files. **Commands** map to top-level recipes at `.goose/recipes/.yaml` (project) and `~/.config/goose/recipes/.yaml` (global); the command body becomes the recipe `prompt`, `title` defaults to the file name and `description` to the rulesync `description` (falling back to `title`), `version` defaults to `1.0.0`, and any other recipe field round-trips through the rulesync `goose` section of a command.\n\n**Subagents** map to Goose\'s [custom agents](https://block.github.io/goose/docs/guides/context-engineering/custom-agents/) (v1.34.0+): Markdown files with `name` (required) / `description` / `model` frontmatter whose body is the agent instructions, invocable via `@name` or delegation. They are emitted to the goose-specific discovery dirs `.goose/agents/.md` (project) and `~/.config/goose/agents/.md` (global), so the output cannot collide with a future shared `.agents/agents/` target; `model` and unknown future fields round-trip through the rulesync `goose` subagent section. Earlier rulesync versions emitted subagents as sub-recipe YAML under `.goose/recipes/subagents/` — a location Goose\'s agent discovery never scans, so those files were inert; they are no longer generated (stale outputs stay gitignored but are not cleaned up automatically).\n\n### Vibe-specific: stdio `cwd` and MCP `[auth]` block\n\nVibe (mistral-vibe) MCP servers live in `[[mcp_servers]]` arrays of the shared `.vibe/config.toml`. In addition to the flat fields, Rulesync passes through the stdio `cwd` (working directory), a structured per-server `auth` block (Vibe v2.15.0+), and the four keys Vibe\'s `/mcp` panel writes back when you toggle a server or one of its tools — `prompt`, `sampling_enabled`, `disabled` and `disabled_tools`. Because `mcp_servers` is replaced as a whole array on each generate, a server Rulesync writes is seeded from the on-disk entry of the same name for exactly those keys, so a toggle you made in the TUI survives — unless your `.rulesync/mcp.json` states the value itself, which wins. `disabled_tools` is the canonical `disabledTools` under Vibe\'s spelling; `prompt` and `sampling_enabled` have no canonical equivalent and pass through as-is. The `auth` table is discriminated on `type`: `static` (`headers`, `api_key_env`, `api_key_header`, `api_key_format`) and `oauth` (`scopes`, `client_id` / `client_metadata_url`, `redirect_port`). Because Vibe rejects mixing legacy top-level static-auth keys with an explicit `[auth]` block, Rulesync suppresses the legacy keys (`headers`/`api_key_env`/`api_key_header`/`api_key_format`) whenever a server carries an `auth` block. Servers added outside Rulesync — through `vibe mcp add` (v2.23.0) or the `/mcp add` panel, both of which persist straight into this TOML — are preserved after the managed entries instead of being deleted by the array replace. The flip side: removing a server from `.rulesync/mcp.jsonc` no longer removes it from `config.toml`; delete it there too (or run `vibe mcp remove`). See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/config/models.py`).\n\n> **GitHub Copilot (VS Code) MCP note:** the `copilot` target writes `.vscode/mcp.json`, which has three documented top-level sections: `servers`, `inputs` (secret prompts referenced as `${input:id}`) and `sandbox` (filesystem/network rules for sandboxed servers, added in VS Code v1.112). Rulesync owns and replaces only `servers`; the rest of the document — including any future top-level section — is read back and preserved on each generate. VS Code recommends committing this file, so dropping an `inputs` entry would leave `${input:…}` unresolvable and the affected servers would fail to start. If the existing file cannot be parsed, generate fails with an error rather than overwriting it. See the [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).\n\n> **Rovo Dev CLI MCP note:** Rovo Dev documents the per-server transport key as `transport` (`stdio` | `http` | `sse`), not the canonical `type`. Rulesync translates on the way out (`local` → `stdio`, `streamable-http` → `http`) and back on import; `ws` has no Rovo Dev equivalent, so those servers are skipped with a warning, and a `transport` value outside Rovo Dev\'s vocabulary is dropped on import rather than written into the canonical config, whose transport field is a strict enum. `disabled` is stripped from the servers that are written, since `mcp.json` is not where a Rovo Dev server is switched on and off — see the toggle handling below. `mcp.json` is written at both scopes: the global `~/.rovodev/mcp.json`, and in project mode the repo-committed `.rovodev/mcp.json` the Bitbucket Cloud Agentic Pipelines guide documents (pointed at via `mcp.mcpConfigPath`; not gitignored, since committing it is the point). A server the canonical config marks `disabled: true` is no longer dropped: its definition is written to `mcp.json` (minus the flag, which the file cannot express) and its name goes to `mcp.disabledMcpServers` in the sibling `config.yml` — the key Rovo Dev actually consults — where rulesync owns the toggle for the servers it manages while user keys (`mcpConfigPath`, `allowedMcpServers`, ...) and disabled names for unmanaged servers survive. On import, names listed in `mcp.disabledMcpServers` come back as `disabled: true` on the matching servers; a `config.yml` that exists but cannot be parsed fails both directions closed (the import errors instead of silently re-enabling servers, and generate skips disabled definitions it cannot switch off). Since the project `mcp.json` is committed, prefer env-var references over literal credentials in server `env`/`headers`; note that rulesync owns the `mcpServers` map in that file, so servers hand-added there (rather than to `.rulesync/mcp.jsonc`) are replaced on the next generate. See the [Rovo Dev MCP docs](https://support.atlassian.com/rovo/docs/connect-to-an-mcp-server-in-rovo-dev-cli/).\n\n> **Reasonix note:** MCP servers are written as `[[plugins]]` array-of-tables entries (Reasonix\'s MCP-compatible external plugins) in `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`). Each entry carries a `name` plus the standard transport fields: `type` selects the transport (`stdio` default — `command`/`args`/`env`; `http`, a.k.a. `streamable-http` — `url`/`headers`; `sse`, the legacy 2024-11-05 HTTP+SSE transport, written verbatim — Reasonix re-implemented it in v1.17.18, and collapsing it onto `http` pointed the client at Streamable HTTP so the server could not connect). The file is treated as shared Reasonix config: Rulesync only replaces the `plugins` key and preserves every other table (providers, ui, agent, …) on round-trip, and it is never deleted. Reasonix has no per-server tool allow/deny lists. The `trusted_read_only_tools` array (raw MCP tool names pre-seeded as trusted for planner/read-only use) is neither written nor imported: v1.17.18 retired it along with `default_tools_approval_mode`, `tools..approval_mode` and `approvals_reviewer` — installing a server is the authorization decision now, and Reasonix ignores the key on load and strips it the next time it saves that entry. Importing it would put a Reasonix-only dead key into the canonical `mcpServers` that every MCP target writes out, so it would surface in `.mcp.json` and the rest. Note that Rulesync owns the `plugins` key, so the next generate drops the key from an older `reasonix.toml` as well; nothing is lost that Reasonix still reads. An MCP server whose transport Reasonix does not implement (`ws`, including a `ws://`/`wss://` URL that states no transport at all) is skipped with a warning rather than written as a `type` its loader rejects. Each entry also supports `call_timeout_seconds` (a per-server MCP call timeout) and `tool_timeout_seconds` (a per-tool inline table keyed by raw MCP tool name). None of these have a deep canonical mapping, so they round-trip as passthrough fields on the canonical MCP server object. See the [Reasonix plugins guide](https://github.com/esengine/deepseek-reasonix/blob/main-v2/docs/GUIDE.md#plugins-mcp) and [SPEC.md](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md) (`[[plugins]]` schema).\n\n## `.rulesync/.aiignore` or `.rulesyncignore` (deprecated)\n\n> **Deprecation notice:** The `ignore` feature is deprecated in favor of the more expressive [`permissions` feature](#rulesync-permissions-jsonc). Existing ignore configurations, generation, import, conversion, and explicit `rulesync add ignore` scaffolding remain supported throughout Rulesync 14.x. Removal, if any, will be decided separately and will not occur before a future major release. `rulesync init` no longer enables or scaffolds ignore for new projects.\n\nRulesync continues to support a single legacy ignore list in either location:\n\n- `.rulesync/.aiignore` (preferred legacy location)\n- `.rulesyncignore` (older project-root location)\n\nRules and behavior:\n\n- You may use either location.\n- When both exist, Rulesync prefers `.rulesync/.aiignore` over `.rulesyncignore` when reading.\n- Explicitly running `rulesync add ignore` creates `.rulesync/.aiignore` when neither location exists.\n\nExample:\n\n```ignore\ntmp/\ncredentials/\n```\n\n### Migrating to permissions\n\nMove each ignore pattern into the `read` category of `.rulesync/permissions.jsonc` with the `deny` action:\n\n```jsonc\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json",\n "permission": {\n "read": {\n "tmp/**": "deny",\n "credentials/**": "deny",\n },\n },\n}\n```\n\nThis is the closest replacement for preventing an agent from reading ignored paths. If the old policy was also intended to prevent changes, repeat the patterns under `edit` and `write`. Target tools differ in the permission categories they can represent, so review the [Supported Tools and Features](./supported-tools.md) table and the tool-specific permission notes below before removing the old ignore feature from a multi-tool project.\n\n### Where ignore patterns are written per tool\n\nMost tools get a dedicated ignore file (for example `.cursorignore`,\n`.geminiignore`, `.clineignore`). Antigravity CLI is built on the same engine\nas Gemini CLI, so it reads the project-root `.geminiignore` file. Claude Code is the exception: it does not\nread a separate ignore file, so Rulesync writes the deny list into Claude\nCode\'s settings file as `permissions.deny` entries (`Read()`).\n\nReasonix has no ignore file either, so its deny list goes into the `[permissions]` table of the shared `reasonix.toml` (project) / `~/.reasonix/config.toml` (global, via `--global`) as `Read()` entries — the same Claude-Code-style rule syntax the permissions feature writes there. `deny` is used rather than `[sandbox].forbid_read` because deny rules take glob specifiers and are documented as "a hard block in every mode", while `forbid_read` takes absolute paths with no documented glob support. The file is shared with the MCP and permissions features: only `Read(...)` deny entries are replaced, every other table and deny entry is preserved, and the file is never deleted. When the permissions feature also manages the `Read` category its explicit rules win, and the overwrite is warned about. As with the MCP and permissions features, the file is re-serialized on write, so hand-written comments, blank lines, and key ordering in `reasonix.toml` are not preserved.\n\nKiro reads `.kiroignore` in project scope and `~/.kiro/settings/kiroignore` in user scope. The `kiro`, `kiro-cli`, and `kiro-ide` targets therefore support `--global` for the deprecated ignore feature, as do `reasonix` and `zed` (whose config files exist in both scopes); the remaining ignore targets are project-only.\n\nZed has no ignore file: its deny list is the `private_files` array inside the shared settings file — `.zed/settings.json` in project scope and `~/.config/zed/settings.json` in global scope (`%APPDATA%\\Zed\\settings.json` on Windows). `private_files` is a worktree setting, and Zed layers default → user → project, so the key is honored in the user settings file too. The array is **owned wholesale by Rulesync**: it is replaced with the patterns from `.rulesync/.aiignore` on every generation, so a pattern deleted there is retracted from `settings.json` instead of surviving forever. When no patterns remain at all, the key is removed rather than written as `[]` — Zed ships a populated default `private_files` (`**/.env*`, `**/*.pem`, …) that any user or project value replaces wholesale, so an empty array would switch its secret redaction off. Every other key in the file — including the MCP `context_servers` and permissions `agent` blocks and unrelated editor settings — is preserved, and the file is never deleted.\n\nGoose retired `.gooseignore` upstream ("removed some time ago in favour of other ignore things like gitignore etc" — [goose#10343](https://github.com/aaif-goose/goose/issues/10343)), so rulesync no longer generates it; the replacement guidance is `.gitignore` plus tool permissions. Stale `.gooseignore` files from earlier versions stay gitignored but are not cleaned up automatically.\n\nCline\'s `.clineignore` is still emitted, but its own docs now title it "deprecate soon" and state it is not a security or access-control boundary — upstream\'s replacement direction is a Cline plugin enforcing via a `beforeTool` hook. Treat the matrix ✅ as a deprecated surface.\n\nHermes Agent uses a project-local `rulesync-ignore` plugin under `.hermes/plugins/`. It applies the canonical gitignore-style patterns through [`pre_tool_call`](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/#pre-tool-call) to `read_file`, `write_file`, and `patch` before execution, and filters ignored paths from `search_files` results through `transform_tool_result`. This is defense in depth around Hermes file tools; terminal commands and paths already present in conversation context are outside the plugin\'s enforcement surface. Hermes deliberately requires [explicit trust for project plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins/), so run it from the trusted project root with that invocation opted in:\n\n```sh\nHERMES_ENABLE_PROJECT_PLUGINS=1 hermes\n```\n\nRulesync adds `rulesync-ignore` to `plugins.enabled` in `$HERMES_HOME/config.yaml` but deliberately leaves `$HERMES_HOME/.env` unchanged. Existing configuration is preserved, explicit `plugins.disabled` conflicts fail, and `--delete` retains the additive user-level activation.\n\nFor Cursor, Rulesync emits only `.cursorignore` — the file that **blocks access\nentirely** (semantic search, Tab, Agent, Inline Edit, and `@`-mentions). Cursor\nalso supports a second file, `.cursorindexingignore`, which excludes files from\n**indexing only** while keeping them accessible to the AI on demand. These two\nfiles mean _different_ things, and Rulesync\'s `ignore` feature models a single\ncanonical ignore list per tool with no per-pattern distinction between\n"block access" and "exclude from indexing only". Emitting the same patterns to\nboth files would be incorrect, so `.cursorindexingignore` is intentionally **not\ngenerated** (an intentional non-goal). Author it by hand if you need\nindexing-only excludes.\n\nBy default, Claude Code\'s deny list is written to the **shared**\n`.claude/settings.json` so that the policy can be committed and reviewed by\nthe team. This is intentional (see issue #1094), but it means that running\n`rulesync gitignore` will not add `.claude/settings.json` to `.gitignore` —\nthat file may also contain other shared Claude config you actively want to\ncommit.\n\nIf you would rather keep the deny list out of version control, opt into the\n**local** mode using the per-feature options object form:\n\n```jsonc\n// rulesync.jsonc\n{\n "targets": ["claudecode"],\n "features": {\n "claudecode": {\n "ignore": { "fileMode": "local" },\n },\n },\n}\n```\n\n| `fileMode` | Output file | Tracked by git by default |\n| -------------------- | ----------------------------- | ----------------------------------------------------- |\n| `"shared"` (default) | `.claude/settings.json` | Yes — meant to be committed and shared with the team. |\n| `"local"` | `.claude/settings.local.json` | No — `rulesync gitignore` already excludes this file. |\n\n## `.rulesync/permissions.jsonc`\n\n`.rulesync/permissions.jsonc` is the recommended source path and accepts comments and trailing commas. The legacy `.rulesync/permissions.json` path remains readable for existing projects. When both files exist, the JSONC file takes precedence; write flows update the existing source instead of creating a second variant.\n\nFor Hermes Agent imports, Rulesync treats a valid private `permissions.rulesync` block as provenance, then reconciles it with current native settings. `command_allowlist`, `approvals.deny`, and an enabled `security.website_blocklist` are authoritative for their mapped canonical rules, so hand edits replace stale generated values. A config with no private block still imports those native rules. Unmodeled `approvals`, `security`, `skills`, and `memory` settings remain under the `hermes` override; unrelated root settings such as `model` are not imported.\n\n`rulesync init` scaffolds a `codexcli` block with `approval_policy: "on-request"`, `approvals_reviewer: "auto_review"`, and `base_permission_profile: ":danger-full-access"`. On generation, the profile value becomes Codex\'s top-level `default_permissions`.\n\nPermissions define which tool actions are allowed, require confirmation, or are denied. The canonical format uses **lowercase tool category names** and **glob patterns** mapped to permission actions.\n\n**Permission actions:**\n\n- `allow` -- Automatically permitted without user confirmation\n- `ask` -- Requires user confirmation before execution\n- `deny` -- Blocked from execution\n\n**Supported tool categories:** `bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, and MCP-specific tool names (e.g., `mcp__puppeteer__puppeteer_navigate`)\n\nExample:\n\n```json\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json",\n "permission": {\n "bash": {\n "git *": "allow",\n "npm run *": "allow",\n "rm -rf *": "deny",\n "*": "ask"\n },\n "edit": {\n "src/**": "allow"\n },\n "read": {\n ".env": "deny",\n "credentials/**": "deny"\n }\n }\n}\n```\n\n### Tool-scoped permission blocks (`{toolname}.permission`)\n\nThe shared `permission` block applies to every targeted tool. To scope rules to a single tool, add a tool-scoped `{toolname}` block with a `permission` record of the same shape — mirroring `{toolname}.hooks` in `.rulesync/hooks.jsonc` and `{toolname}.mcpServers` in `.rulesync/mcp.jsonc`:\n\n```jsonc\n{\n "permission": {\n "bash": { "git *": "allow", "*": "ask" },\n },\n "claudecode": {\n "permission": {\n // Replaces the shared `bash` category for Claude Code only.\n "bash": { "git *": "allow", "git push *": "deny", "*": "ask" },\n },\n },\n}\n```\n\n- Categories are merged **per category**: a tool-scoped category replaces the shared category wholesale for that tool; shared categories it does not name still apply.\n- Any permissions-capable `--targets` name is accepted as a block key. `kiro-cli`/`kiro-ide` alias to the `kiro` key and `hermesagent` to `hermes` (matching the shared output file each writes).\n- OpenCode, Kilo, and Vibe keep their existing tool-native `permission` override semantics (bare action strings / tool-only categories / `sensitive_patterns` — see the tool-specific callouts below); their blocks are consumed by their translators instead of the central merge.\n\n#### JSON Schema Support\n\nRulesync provides a JSON Schema for editor validation and autocompletion. Add the `$schema` property to your `.rulesync/permissions.jsonc`:\n\n```json\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/permissions-schema.json",\n "permission": {}\n}\n```\n\nFor Claude Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.claude/settings.json` (project mode) or `~/.claude/settings.json` (global mode) using PascalCase tool names (e.g., `Bash(git *)`, `Edit(src/**)`, `Read(.env)`).\n\nClaude Code\'s file permission checks match only `Edit(path)` and `Read(path)` rules: a `Write(path)`, `NotebookEdit(path)` or `Glob(path)` rule "is accepted but never matched by those checks, so Claude Code warns at startup for each allow, deny, or ask rule in one of these unmatched forms" ([permissions docs](https://code.claude.com/docs/en/permissions), v2.1.210+). Rulesync therefore writes a canonical `write` or `notebookedit` rule that carries a pattern as `Edit(pattern)`, and a `glob` rule as `Read(pattern)`. A rule whose pattern is `*` is a tool-name rule with no path — it matches the tool everywhere and produces no warning — so it is still written as the bare `Write` / `NotebookEdit` / `Glob`. Entries an earlier Rulesync wrote in the warned form are replaced on the next generate, and so is a rewritten entry whose action changed, so flipping a rule from deny to allow never leaves the old deny behind to win. Rewriting a rule does **not** make Rulesync claim the `Edit` or `Read` namespace as a whole: a `Read(...)` deny the [ignore feature](#rulesyncignore) wrote, or an `Edit(...)` rule you added to `settings.json` by hand, is left alone unless the canonical config manages that category itself. Import stays tolerant of both forms, so an existing `settings.json` still round-trips; a rewritten rule comes back under `edit` or `read` rather than the category it was authored in, since that is the rule Claude Code actually applies. Note that this widens a `glob` **allow** rule: `Read(pattern)` permits reading the files\' contents, not just listing their names — the docs prescribe the substitution, but author `glob` allow rules with that in mind. When two categories resolve to the same entry with different actions (`edit` allowing what `write` denies, say) both are written and Rulesync warns — Claude Code applies deny first, then ask, then allow.\n\n> **Claude Code-only override (`claudecode` key):** Claude Code\'s `permissions` object also carries non-list fields with no canonical permission category — notably `defaultMode` (the session-start permission mode: `default` | `acceptEdits` | `plan` | `bypassPermissions`) and `additionalDirectories` (extra working directories). Add a tool-scoped `claudecode` override key alongside the shared block to author them: the fields under `claudecode.permissions` are merged into the settings `permissions` object and emitted **only** for Claude Code, while the shared `permission` block continues to drive the managed `allow`/`ask`/`deny` arrays. The block is a verbatim passthrough (so other/future `permissions` fields such as the org locks `disableBypassPermissionsMode`/`disableAutoMode` can be set too), but any `allow`/`ask`/`deny` placed inside it is ignored — rulesync owns those arrays. On import, the non-list `permissions` fields round-trip back into the `claudecode` override. Note that these fields are merged **additively** into the existing `settings.json` (so hand-added settings survive): removing a field from the `claudecode` override does not delete a value already written to `settings.json` — clear it there by hand.\n>\n> ```json\n> {\n> "permission": { "bash": { "git *": "allow" } },\n> "claudecode": {\n> "permissions": { "defaultMode": "acceptEdits", "additionalDirectories": ["../shared"] },\n> "sandbox": { "network": { "allowedDomains": ["example.com"], "strictAllowlist": true } }\n> }\n> }\n> ```\n>\n> The same override key also carries `sandbox`, the sibling top-level settings subtree governing the sandbox commands run in (`sandbox.network.*`, `sandbox.filesystem.*`, `sandbox.credentials`, `sandbox.allowAppleEvents`, ...). It has no canonical permission category either — it constrains _how_ a permitted command runs rather than which commands are permitted — so it is a verbatim passthrough on the same terms, merged into the top level of `settings.json` and round-tripped back on import. The merge is recursive, unlike the flat `permissions` fields above: `sandbox` subtrees carry restriction lists (`network.deniedDomains`, `filesystem.denyRead`), so setting one flag under `network` must not drop the denials beside it. A sibling key at any depth survives; a list you author replaces the existing list rather than being appended to. See the [sandboxing docs](https://code.claude.com/docs/en/sandboxing).\n\nFor OpenCode, this generates the `permission` object in `opencode.json` / `opencode.jsonc` (project mode) or `.config/opencode/opencode.json` / `.config/opencode/opencode.jsonc` (global mode), preserving other existing OpenCode config fields. OpenCode\'s `webfetch`, `websearch`, `todowrite`, `question`, and `doom_loop` keys accept only a single action string, so Rulesync emits their canonical `{ "*": "allow" }` form as `"allow"`. If one of these categories contains pattern-specific rules, Rulesync collapses them to the most restrictive action (`deny` > `ask` > `allow`) and logs a warning because OpenCode cannot represent those patterns; a map without `*` includes an implicit `ask` fallback so a narrow allowlist never becomes blanket `allow`, while an empty map becomes `deny` instead of falling through to OpenCode\'s default allow behavior.\n\n> **OpenCode-only override (`opencode` key):** OpenCode exposes permission categories that other tools do not understand (e.g. `external_directory`). Placing these in the shared `permission` block would push meaningless entries into Claude Code, Codex, etc. To scope them to OpenCode, add a tool-scoped `opencode` override key alongside the shared block — mirroring the tool-scoped override keys used by [hooks](#hooks) (`opencode.hooks`) and rules frontmatter. Categories under `opencode.permission` are merged on top of the shared block **per category** (the override wins) and are emitted **only** into `opencode.json` / `opencode.jsonc`; every other tool ignores them. Values may use a bare action string (`"deny"`) or, for OpenCode keys that support fine-grained matching, a pattern map (`{ "*": "ask" }`).\n>\n> ```jsonc\n> {\n> "permission": {\n> "bash": { "git *": "allow", "*": "ask" },\n> },\n> // Emitted only into opencode.json\'s `permission`; never leaks to other tools.\n> "opencode": {\n> "permission": {\n> "external_directory": "deny",\n> },\n> },\n> }\n> ```\n>\n> On **import**, any OpenCode category that is not a shared canonical rulesync category (`bash`, `read`, `edit`, `write`, `webfetch`, `websearch`, `grep`, `glob`, `notebookedit`, `agent`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `opencode` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> You may also override a **shared** category for OpenCode specifically (e.g. put `webfetch` under `opencode.permission` to give OpenCode a different value than the shared block sends to other tools). On generate this works as expected, but note the override is not round-trip stable for shared categories: re-importing the generated `opencode.json` classifies a shared category back into the shared block, so prefer expressing OpenCode-only categories here and keeping cross-tool categories in the shared block.\n\nFor Hermes Agent, permissions are written into the shared `~/.hermes/config.yaml` (global only). Canonical rules map onto the structures Hermes\'s runtime actually enforces:\n\n- `allow` patterns (all categories) → `command_allowlist`.\n- `bash` `deny` patterns → `approvals.deny` — Hermes\'s hard denylist, evaluated **before** `--yolo` / `approvals.mode: off`.\n- `webfetch` `deny` patterns → `security.website_blocklist.domains`.\n- Every `ask` rule, and `deny` rules in categories other than `bash`/`webfetch`, have no native per-pattern Hermes primitive; they survive only for round-trip (Rulesync also stores the full canonical config under a private `permissions.rulesync` key so `.rulesync/permissions.jsonc` reconstructs losslessly).\n\n> **Hermes-only override (`hermes` key):** Hermes exposes approval/security controls with no canonical permission category — e.g. `approvals` (`mode`, `cron_mode`, `mcp_reload_confirm`, ...), `security` (`allow_private_urls`, ...), `skills.write_approval`, `memory.write_approval`. Add a tool-scoped `hermes` override key alongside the shared block to author them; its contents are **deep-merged** into `config.yaml` (so an `approvals.mode` here coexists with the `approvals.deny` derived from canonical deny rules) and are emitted **only** for Hermes. The block is a verbatim passthrough, so any current or future Hermes config key can be set without Rulesync modeling each one. Note that the deep merge replaces **arrays** wholesale, so setting `hermes.approvals.deny` or `hermes.security.website_blocklist.domains` overrides (does not append to) the list derived from the shared `permission` block — use it only when you intend to replace the canonical-derived deny list for Hermes. The top-level `permissions` key is reserved by Rulesync for the round-trip blob, so a `permissions` key inside the `hermes` override is ignored.\n>\n> ```json\n> {\n> "permission": { "bash": { "rm -rf *": "deny" } },\n> "hermes": { "approvals": { "mode": "smart" }, "security": { "allow_private_urls": false } }\n> }\n> ```\n\nFor Codex CLI, this generates a `rulesync` named profile in `.codex/config.toml` under `[permissions.rulesync]` and sets `default_permissions = "rulesync"` (project/global depending on mode). It also generates `.codex/rules/rulesync.rules` from `permission.bash` entries using `prefix_rule(...)`. Current Rulesync-to-Codex mapping supports `bash`, `read`, `edit`/`write`, and `webfetch` categories:\n\n- `bash`: generates one `prefix_rule(...)` per command pattern in `.codex/rules/rulesync.rules` (`allow` → `allow`, `ask` → `prompt`, `deny` → `forbidden`)\n- `read`: `allow` → `read`, `ask`/`deny` → `deny` in `permissions..filesystem`\n- `edit` / `write`: `allow` → `write`, `ask`/`deny` → `deny` in `permissions..filesystem`\n- `webfetch`: `allow`/`deny` map to `permissions..network.domains` (Codex does not support `ask` for domain rules); `network.enabled = true` is emitted only when at least one `allow` rule is present. Deny-only domain sets are emitted without `enabled`, which Codex treats as restricted (its default) while the deny entries still round-trip back into Rulesync rules. Codex rejects the global wildcard `*` in denied domains at config load time, so `webfetch: { "*": "deny" }` is skipped with a warning (unlisted domains are denied by Codex\'s allowlist-first policy anyway); `webfetch: { "*": "allow" }` is emitted as a regular `"*" = "allow"` domain entry, which Codex accepts for denylist-only setups ([openai/codex#15549](https://github.com/openai/codex/pull/15549)). On import, `deny` entries are always taken, while `allow` entries are imported only when `enabled = true` is explicit — Codex treats a missing `enabled` as restricted, so importing an allow entry from a disabled profile would activate a grant Codex never had. A Codex profile with `network.enabled = true` but no `domains` is imported as `webfetch: { "*": "allow" }`, which reflects Codex\'s default semantics where `enabled = true` grants sandbox-wide network access (under Codex\'s experimental `network_proxy` feature, `enabled = true` without an allowlist blocks requests instead, and the regenerated `"*" = "allow"` entry is the closest equivalent).\n\nRelative filesystem globs such as `src/**` or `**/*.tf` are emitted under `permissions..filesystem.":workspace_roots"` instead of the top-level filesystem table, because Codex expects top-level filesystem keys to be absolute paths, `~/...`, or named roots. Rulesync also sets `glob_scan_max_depth = 8` when generated workspace-root rules contain unbounded `**` patterns.\n\nThe `:workspace_roots` table also receives a default `.git` carve-out: `".git/**" = "write"`. Codex\'s `:workspace` baseline keeps `.git` read-only inside workspace roots, which denies basic git workflows (commit/stage operations write to `.git/index`, `.git/objects`, refs, and logs; everyday commands such as `git remote add`, `git push -u`, and local-scope `git config` write to `.git/config`). The write rule reopens the whole subtree, including `.git/config` — an earlier `".git/config" = "read"` security guard (a writable `.git/config` lets a sandboxed process set keys like `core.fsmonitor` or `core.hooksPath` that execute code outside the sandbox) was dropped because it blocked those everyday commands while the protection it added was already partial (`.git/hooks/`, and `.git/modules/**` for submodules, remains writable so hook managers such as lefthook and simple-git-hooks keep working; a sandboxed process could still install a hook directly). Users who want stricter isolation can author a more specific rule (e.g. `read: { ".git/config": "allow" }` or `read: { ".git/hooks/**": "allow" }`) in the canonical permissions, which wins over the default (Codex resolves the more specific path with priority). Because `.git/**` is an unbounded `**` pattern, the carve-out also means `glob_scan_max_depth = 8` is effectively always emitted unless it is suppressed.\n\nThe carve-out is skipped in three cases: a user rule for the same pattern always wins per key; the `codexcli.git_write_rules` override set to `false` suppresses it entirely (only an explicit `false` does; the default is `true`); and it is not injected when `codexcli.base_permission_profile` is `":read-only"` (it would grant `.git` write access inside a sandbox the user explicitly chose to keep read-only) or when the canonical rules contain a direct `":workspace_roots"` pattern (a whole-tree access decision that the defaults must not override). Like `:minimal`, the default-valued carve-out is not imported into the Rulesync model on `rulesync import` — it is re-added on every generate — while customized `.git` values import normally. One limitation: the `git_write_rules` flag itself cannot be recovered from `config.toml`, so it does not round-trip through `rulesync import`; if you opted out with `false`, re-add the flag to the canonical permissions config after importing (and if you want the same `.git` rules while opted out, author them as canonical `read`/`write` rules rather than hand-writing them in `config.toml` — though note that import cannot tell a user-authored `".git/**" = "write"` from the default carve-out, so that exact pattern/value pair is still skipped on import and must be re-authored in the canonical config afterwards). Migration note: configs generated before the `".git/config" = "read"` default was removed still carry that entry, and `rulesync import` now treats it as a user-authored rule — it lands in the canonical config as `read: { ".git/config": "allow" }` and, because Codex gives the more specific path priority, keeps `.git/config` read-only on every regenerate. If you want the current writable default instead, delete that rule from the canonical permissions after importing.\n\nThe generated `[permissions.rulesync]` profile always extends one of Codex\'s built-in permission profiles via `extends`. The baseline is chosen with the `codexcli.base_permission_profile` override key (`":read-only"` | `":workspace"` | `":danger-full-access"`) and defaults to `":workspace"` when unspecified. Codex\'s built-in `:workspace` baseline grants read access to the whole filesystem and write access to the entire workspace root plus `/tmp` and `$TMPDIR` (with carve-outs protecting `.git`, `.codex`, and `.agents`), while `:read-only` keeps command execution read-only; the generated `filesystem` entries then grant or deny access on top of the chosen baseline. Codex\'s third built-in profile, `:danger-full-access`, is rejected by `extends` at Codex config load time — so selecting it works differently: Rulesync emits `default_permissions = ":danger-full-access"` directly and skips the managed `[permissions.rulesync]` profile entirely (with the sandbox removed there is nothing for filesystem/network rules to refine; canonical `read`/`edit`/`write`/`webfetch` rules are ignored for Codex CLI with a warning, and any stale managed profile from a previous generate is pruned while sibling hand-written profiles are preserved). On import, a profile\'s `extends` value round-trips back into `codexcli.base_permission_profile` when it names one of the two extendable built-ins, and a top-level `default_permissions = ":danger-full-access"` round-trips the same way; a custom parent profile is skipped and replaced by the managed baseline on regeneration (with a warning).\n\nRulesync emits `":minimal" = "read"` in the generated filesystem table by default. This enables `include_platform_defaults()` ([FileSystemSpecialPath::Minimal](https://github.com/openai/codex/pull/13434)), which provides the platform/runtime read access needed for basic sandboxed command execution on macOS, Linux, and Windows. `:minimal` is the only special path treated as a fixed baseline: it is always present in the generated table and is never imported into Rulesync\'s own permission model, regardless of its value. A canonical rule for `:minimal` still overrides the emitted value on generate (e.g. a `write: { ":minimal": "allow" }` rule emits `":minimal" = "write"` — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for when that is needed), but because import always skips `:minimal`, such a customization does not round-trip: after `rulesync import`, re-author the rule or the next generate falls back to `"read"`. The other special paths `:root`, `:tmpdir`, and `:slash_tmp` are user-managed access rules that are imported into the Rulesync model and re-emitted from it like any ordinary filesystem entry (`:root = "deny"` becomes a read/edit deny, `:tmpdir = "write"` becomes an edit allow, and so on). Because they round-trip through `.rulesync/permissions.jsonc` rather than relying on an existing `.codex/config.toml`, a restrictive value such as `:root = "deny"` survives a fresh-clone `rulesync generate` with no pre-existing Codex config.\n\n`network.mode`, `network.unix_sockets`, and `description` have no equivalent in Rulesync\'s canonical permissions model and are not generated. If an existing `.codex/config.toml` already contains these fields on the `rulesync` profile, Rulesync preserves them on regeneration — as it does any other network key it does not model (e.g. `dangerously_allow_all_unix_sockets` or Codex\'s proxy keys), since network settings are user territory by design. `network.enabled` is only half-managed: Rulesync sets `enabled = true` itself when the canonical model contains an allow domain, but when a regeneration computes no `enabled` value, a user-authored `enabled` is preserved (with a warning) instead of being deleted — see the [FAQ](../faq.md#codex-cli-denies-ssh-agent-access-temp-dir-writes-or-reading-its-own-config-with-a-generated-permissions-profile) for the recommended user-managed entries. The preservation applies only when the existing profile carries no allow domain: an existing `enabled` next to allow domains is Rulesync\'s own managed output, so removing every webfetch allow rule from the canonical model removes `enabled` too (falling back to Codex\'s restricted default) instead of leaving an unscoped `enabled = true` behind. Note that `filesystem`, `network.domains`, and `extends` are always managed by Rulesync (`filesystem`/`network.domains` derived from `edit`/`write`/`webfetch` rules, `extends` from `codexcli.base_permission_profile`), so hand-authored values in those fields will be replaced on regeneration.\n\n> **Codex CLI-only override (`codexcli` key):** Codex CLI\'s permission surface is richer than the canonical allow/ask/deny model — its approval workflow, permission-profile baseline, and per-app tool gating have no canonical category. Add a tool-scoped `codexcli` override to author them: except for `base_permission_profile`, its fields are written verbatim as **top-level `.codex/config.toml` keys** (the override wins per key; existing sibling keys the user set directly are preserved, and table values are shallow-merged) while the shared `permission` block keeps driving the managed `[permissions.rulesync]` profile and `default_permissions`. Supported keys: `base_permission_profile` (`:read-only` | `:workspace` | `:danger-full-access`, default `:workspace` — not a top-level key; it becomes the managed profile\'s `extends` baseline, or with `:danger-full-access` the directly-selected `default_permissions` value, see above), `approval_policy` (`untrusted` | `on-request` (legacy alias `on-failure`) | `never`, or a `{ granular = { … } }` table kept verbatim; defaults to `on-request` when neither the override nor the existing config sets it), `apps` (per-app tool gating — `apps..tools..approval_mode` / `.enabled`, `apps..default_tools_approval_mode`), `approvals_reviewer` (`user` | `auto_review` (legacy alias `guardian_subagent`), or a table; defaults to `auto_review` when neither the override nor the existing config sets it), and `git_write_rules` (boolean, default `true` — like `base_permission_profile` it is not a top-level key: it controls whether the managed profile\'s `:workspace_roots` table emits the default `.git` carve-out described above; only an explicit `false` suppresses it). **Deprecated:** `sandbox_mode` (`read-only` | `workspace-write` | `danger-full-access`) with the sibling `sandbox_workspace_write` table (`network_access`, `writable_roots`, …) belong to Codex\'s classic sandbox system, which permission profiles supersede — Codex prioritizes these legacy keys over permission profiles when both are present, so authoring them disables the generated `[permissions.rulesync]` profile; they are still accepted (with a warning) so existing configs round-trip, but use `base_permission_profile` and the shared `permission` block instead. On import, the top-level keys round-trip back into the `codexcli` override, and the managed profile\'s `extends` round-trips into `base_permission_profile`. It is a `looseObject`, so future top-level Codex config keys can be authored here (merged verbatim on generate; only the listed keys are re-extracted on import). Example: `{ "permission": { … }, "codexcli": { "base_permission_profile": ":workspace", "approval_policy": "on-request", "approvals_reviewer": "auto_review" } }`. **Out of scope:** `mcp_servers.*` per-MCP gating is **not** authorable here — it is owned by the MCP feature (`codexcli-mcp.ts` writes the `mcp_servers` tables in the same `config.toml`), and `permissions` / `default_permissions` are owned by the canonical model; any such key placed in the override is skipped with a warning. See the [Codex configuration reference](https://developers.openai.com/codex/config-reference) and [permissions docs](https://developers.openai.com/codex/permissions).\n\nFor Kiro, this generates tool permission settings in `.kiro/agents/default.json` (project mode):\n\n- `bash` maps to `toolsSettings.shell.allowedCommands` / `toolsSettings.shell.deniedCommands`\n- `read` maps to `toolsSettings.read.allowedPaths` / `toolsSettings.read.deniedPaths`\n- `edit` / `write` map to `toolsSettings.write.allowedPaths` / `toolsSettings.write.deniedPaths`\n- `grep` maps to `toolsSettings.grep.allowedPaths` / `toolsSettings.grep.deniedPaths`\n- `glob` maps to `toolsSettings.glob.allowedPaths` / `toolsSettings.glob.deniedPaths` (both emitted only when a rule is present, so existing configs do not gain empty tables)\n- `webfetch` / `websearch` with pattern `*` map to `allowedTools` entries (`web_fetch` / `web_search`)\n- `ask` rules are skipped with a warning (Kiro config does not support explicit ask entries)\n\n> **Kiro-only override (`kiro` key):** Kiro\'s agent config exposes per-tool `toolsSettings` knobs with no canonical allow/ask/deny category. Author them through a tool-scoped `kiro` override under `toolsSettings`: the shell auto-trust flags `shell.autoAllowReadonly` / `shell.denyByDefault`, the `aws` built-in tool\'s `allowedServices` / `deniedServices` (+ `autoAllowReadonly`), and the `web_fetch` domain trust arrays `trusted` / `blocked` (regex host patterns; Kiro documents these for `web_fetch` only — `web_search` has no domain-trust surface). Example: `{ "permission": { … }, "kiro": { "toolsSettings": { "shell": { "autoAllowReadonly": true }, "aws": { "allowedServices": ["s3"], "deniedServices": ["eks"] }, "web_fetch": { "trusted": [".*github\\\\.com.*"] } } } }`. The override is **deep-merged per `toolsSettings` key** (the override wins at the leaf) so authoring `shell.autoAllowReadonly` keeps the canonical-generated `shell.allowedCommands`; the shared `permission` block keeps driving `shell.{allowed,denied}Commands`, `read`/`write`/`grep`/`glob` paths, and the `web_fetch`/`web_search` `allowedTools` toggles. Existing non-canonical `shell` flags are preserved across regenerate even without an override. On **import**, these Kiro-specific surfaces are lifted into the `kiro` override so they round-trip. It is a `looseObject` at every level, so future Kiro `toolsSettings` fields pass through verbatim. Kiro MCP `disabledTools` lives in the separate `.kiro/settings/mcp.json` file and is modeled by the MCP feature; MCP `autoApprove` remains outside this permissions translator. See the [Kiro built-in tools](https://kiro.dev/docs/cli/reference/built-in-tools/) and [configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/) docs.\n\nFor Cursor CLI, this generates `permissions` entries in `.cursor/cli.json` (project mode) or `~/.cursor/cli-config.json` (global mode). Cursor CLI only supports `allow` and `deny` decisions, so `ask` rules are skipped with a warning. Tool categories are mapped to PascalCase Cursor tool names (`bash` → `Shell`, `read` → `Read`, `edit`/`write` → `Write`, `webfetch` → `WebFetch`, `mcp__*` → `Mcp`). Existing Cursor-specific entries that Rulesync does not manage (for example, MCP entries with extra fields) are preserved on round-trip.\n\n> **Cursor-only override (`cursor` key):** Cursor\'s `cli.json` carries scalar autonomy settings with no canonical permission category — `approvalMode` (`allowlist` | `auto-review` | `unrestricted`) and a `sandbox` object (`mode`/`networkAccess`). Add a tool-scoped `cursor` override to author them: its fields are merged into the top level of `cli.json` while the shared `permission` block keeps driving the `permissions.allow`/`permissions.deny` arrays (the override cannot clobber that managed block). On import, `approvalMode` and `sandbox` round-trip back into the `cursor` override. It is a `looseObject`, so `sandbox`\'s (currently undocumented) value set passes through verbatim and extra `cli.json` keys can be authored here (they are merged verbatim on generate); note that only `approvalMode` and `sandbox` are re-extracted on import.\n>\n> ```json\n> {\n> "permission": { "bash": { "git *": "allow" } },\n> "cursor": { "approvalMode": "auto-review" }\n> }\n> ```\n>\n> The separate Cursor **IDE** `permissions.json` (`mcpAllowlist`, `terminalAllowlist`, `autoRun.*`) is a different file and is not targeted by this translator.\n\nFor GitHub Copilot (`copilot`), this manages the three `chat.tools.*.autoApprove` maps in the workspace `.vscode/settings.json` (project mode only). VS Code has no standalone, environment-agnostic Copilot policy file, so project-level auto-approvals are configured through VS Code Copilot Chat\'s workspace settings. Three canonical categories have a clean, non-lossy mapping and are emitted: `bash` → `chat.tools.terminal.autoApprove` (command patterns), `edit` → `chat.tools.edits.autoApprove` (file globs) and `webfetch` → `chat.tools.urls.autoApprove` (URL patterns). In all three, `allow` → `true` (auto-approve) and `deny` → `false` (never auto-approve); an `ask` rule is represented by **omitting** the entry, so VS Code falls through to its default in-chat approval prompt. The canonical `read` category has no VS Code approval surface, and `write` is deliberately **not** folded into the edits map alongside `edit` — doing so would make the two indistinguishable on import — so neither is emitted. VS Code also accepts a `{ "approveRequest": …, "approveResponse": … }` object per URL pattern; that form has no canonical equivalent, so it is skipped on import, and because Rulesync owns the key outright it is replaced whenever the canonical config carries any `webfetch` rule. `.vscode/settings.json` is a general workspace file (JSONC), so Rulesync merges only those three keys non-destructively and never deletes the file; every unrelated setting is preserved. VS Code\'s user-scope `settings.json` lives at a platform-dependent path outside Rulesync\'s home-relative global model, so only project scope is supported. The all-or-nothing `chat.tools.global.autoApprove` boolean and the registry-allowlist `chat.mcp.access` setting are intentionally **not** mapped, since collapsing per-pattern rules into them would misrepresent what was configured. See the [VS Code agent approvals docs](https://code.visualstudio.com/docs/agents/approvals) and the [edit-approval docs](https://code.visualstudio.com/docs/copilot/chat/review-code-edits).\n\nFor Kilo Code, this generates the `permission` object in `kilo.jsonc` (project mode) or `~/.config/kilo/kilo.jsonc` (global mode). The shape is identical to OpenCode\'s (Kilo is an OpenCode fork), so categories like `bash`, `read`, `edit`, `write`, `webfetch`, and `mcp` accept either a string catch-all (`"allow" | "ask" | "deny"`) or a `{ : }` map. Other top-level keys in `kilo.jsonc` are preserved on round-trip. **The `permission` object is merged per top-level tool key**: for each tool key present in the rulesync output, that key is replaced entirely from rulesync (rulesync owns its managed keys; manual edits inside a managed key will be overwritten on the next generation). Tool keys that exist in the existing `kilo.jsonc` but are NOT in the rulesync output are preserved verbatim so user-added Kilo-only categories survive regeneration. When a regenerate replaces a key whose existing value contained `deny` patterns that disappear from the new rulesync output, an aggregated `logger.warn` enumerates the dropped patterns (matching the project convention used by every other permissions translator). Edits to other top-level keys (e.g. `model`) are preserved. **Malformed `kilo.jsonc` aborts the run**: the `jsonc-parser` library would otherwise silently coerce a syntax error to `{}` and overwrite the corrupted file with an empty `permission`, dropping the user\'s existing `deny` rules. Rulesync now surfaces parse errors so the run aborts before any destructive write — matching the strict `JSON.parse` behavior used by every other permissions translator.\n\n> **Kilo-only override (`kilo` key):** Kilo\'s `permission` object carries tool-specific keys with no canonical permission category — OpenCode-inherited ones (`external_directory`, `doom_loop`, `lsp`, `question`, `todowrite`, `skill`, `task`, `list`) and Kilo-unique ones (`agent_manager`, `notebook_read`, `notebook_edit`, `notebook_execute`, `repo_clone`, `repo_overview`). Add a tool-scoped `kilo` override key alongside the shared block (mirroring the `opencode` override) to author these; entries under `kilo.permission` are merged on top of the shared block **per key** (the override wins) and are emitted **only** into `kilo.jsonc`. Each value may be a bare action string or a pattern map. On **import**, any Kilo key that is not a shared canonical category (`bash`, `read`, `edit`, `webfetch`, `websearch`, `grep`, `glob`, the all-tools key `*`, or an `mcp__*` tool name) is routed into the `kilo` override rather than the shared block, so a subsequent `rulesync generate` does not leak it into other tools.\n>\n> **Kilo-only override (`kilo.sandbox`):** the `sandbox` block Kilo runs commands in is a security surface orthogonal to per-tool allow/ask/deny, with no canonical category, so it is authored under the same tool-scoped `kilo` override: `enabled` (boolean), `network` (e.g. `"deny"`), `allowed_hosts` (a list of `host` / `host:port` destination exceptions) and `writable_paths`. It is shallow-merged into the top-level `sandbox` key of `kilo.jsonc` — the override\'s keys win, unrelated sibling keys you set directly are preserved — and the whole block round-trips back into `kilo.sandbox` on import. **Scope matters here.** Kilo honors `allowed_hosts` and `writable_paths` from the _global_ config only, and lets a project config merely tighten (`enabled: true`, `network: "deny"`); a project-level network denial even clears the global destination exceptions. Rulesync mirrors that rather than writing config Kilo would ignore: at project scope only `enabled` and `network` are emitted, and any other key is dropped with a warning telling you to author it with `--global`. See the [sandboxing docs](https://kilo.ai/docs/getting-started/settings/sandboxing).\n\n> **Name-mismatch traps.** Canonical category names do not always match Kilo\'s key names: Kilo folds **`write` into `edit`** (there is no `write` key), uses **`notebook_edit`** (not the canonical `notebookedit`) and **`task`/`agent_manager`** (not `agent`), and has **no `mcp` key** (MCP is addressed via `mcp__*` tool-name keys). Rulesync passes key names through verbatim, so author Kilo keys using Kilo\'s own names (e.g. put a `notebook_edit` rule under `kilo.permission`, not the canonical `notebookedit`). Kilo also treats a `null` action as a delete sentinel; Rulesync does not model `null` and only round-trips `allow`/`ask`/`deny`.\n\nFor AugmentCode CLI, this generates `toolPermissions` entries in `.augment/settings.json` (project mode) or `~/.augment/settings.json` (global mode). Each entry has `toolName`, an optional `shellInputRegex` (only for shell commands), and `permission.type` ∈ `"allow" | "deny" | "ask-user"`. Tool category mapping: `bash` → `launch-process`, `read` → `view`, `edit` → `str-replace-editor`, `write` → `save-file`, `webfetch` → `web-fetch`, `websearch` → `web-search`. Action mapping: rulesync `ask` → AugmentCode `ask-user`. For `bash` patterns other than `*`, the glob pattern is converted to a regex and emitted as `shellInputRegex`. The glob → regex conversion maps `*` to `.*`, `?` to `.`, escapes `\\^$.|+(){}[]`, and anchors at both ends; characters outside that set (notably `-`, `/`, `:`, `,`) are emitted verbatim, so Augment will match them literally. Generated entries are sorted **deny first, ask second, allow last**, with more specific patterns (those carrying `shellInputRegex`) before catch-alls — this is required because Augment\'s `toolPermissions` is evaluated **first-match-wins**. Existing `toolPermissions` entries whose `toolName` is NOT in the rulesync-managed set are preserved on round-trip; existing **`deny` entries for ANY managed `toolName`** (`launch-process`, `view`, `str-replace-editor`, `save-file`, `web-fetch`, `web-search`) are also preserved (fail-closed) so a user-added deny rule on any managed tool cannot be silently downgraded by regeneration. Existing managed-tool `allow` / `ask-user` entries are still replaced (rulesync owns the permissive surface for managed namespaces). **Non-bash categories do not have a documented per-input matcher in AugmentCode**, so Rulesync emits at most one catch-all entry per tool: if the rulesync category contains any `deny` rule, Rulesync emits a single `deny` entry for the entire tool (fail-closed) and warns; otherwise only `*`-pattern allow/ask rules are emitted and any non-`*` allow/ask patterns are dropped with a warning. Importing AugmentCode entries back into rulesync recovers `bash` patterns from `shellInputRegex` but the other categories always import as the catch-all `*` pattern. **The import direction also applies fail-closed precedence** when multiple existing entries collapse to the same `(canonical, "*")` key (e.g. `[{view: deny}, {view: allow}]`): the most restrictive action wins regardless of iteration order (precedence: `deny` > `ask` > `allow`), so a user-added deny in the source file is never silently dropped by import order. The `launch-process` (bash) path is unchanged because each entry has its own `shellInputRegex`-derived pattern with no `"*"` collapse. On **import** (project scope), Rulesync also reads the layered overrides file `/.augment/settings.local.json` — a gitignored, machine-specific file that Auggie merges on top of `settings.json` — and combines it over the base settings before converting to the canonical model, following Auggie\'s documented layering (simple values take the local override, `mcpServers`/`plugins` replace wholesale, and other objects/lists — including `toolPermissions`, which Auggie concatenates local-first under first-match — are combined across tiers), so personal permission overrides are picked up without dropping a committed base `deny`. This overlay is **import-only and project-only**: Rulesync never writes `settings.local.json` (it stays a user-owned, gitignored file), and AugmentCode documents no global `~/.augment/settings.local.json`, so the overlay is skipped in global mode. An unknown top-level key such as `recommendedMarketplaces` (added in Auggie CLI 0.20.0) is preserved verbatim through the generate round-trip via the `{...settings}` merge.\n\n> **AugmentCode-only override (`augmentcode` key):** AugmentCode\'s `toolPermissions[]` supports "custom policy" entries the canonical allow/ask/deny model cannot express — `permission.type` of `webhook-policy` / `script-policy` (delegating the decision to a `webhookUrl` / `script`) and an `eventType` of `tool-response` (a post-execution check rather than the default pre-execution `tool-call`). Author these through a tool-scoped `augmentcode` override with a `toolPermissions` array of verbatim entries: `{ "permission": { … }, "augmentcode": { "toolPermissions": [ { "toolName": "github-api", "permission": { "type": "webhook-policy", "webhookUrl": "https://api.example.com/validate" } }, { "toolName": "view", "eventType": "tool-response", "permission": { "type": "allow" } } ] } }`. Authored entries are **prepended** — ahead of the canonical-generated basic rules — so a webhook/script gate or tool-response check is never shadowed by a regenerated allow/deny/ask entry under first-match-wins. When the override authors `toolPermissions` it becomes the source of truth for the special entries (the existing file\'s specials are no longer separately preserved, avoiding a double-emit); without an override, any special entries already present in `settings.json` are preserved verbatim as before. On **import**, special entries are lifted verbatim into the `augmentcode` override (rather than being skipped with a warning) so they round-trip and become user-authorable; basic entries continue to drive the shared `permission` block. The entry objects stay a loose passthrough so `shellInputRegex`, `webhookUrl`, `script`, and future non-policy fields survive untouched, while the documented bounded fields are validated as enums: `permission.type` (`allow` | `deny` | `ask-user` | `webhook-policy` | `script-policy`) and `eventType` (`tool-call` | `tool-response`). Both project and global scope are supported.\n\nFor Factory Droid, this generates `commandAllowlist` / `commandDenylist` arrays in `.factory/settings.json` (project mode) or `~/.factory/settings.json` (global mode). Factory Droid only gates **shell commands** through these two lists, so only the rulesync `bash` category is translated: `allow` patterns become `commandAllowlist` entries (run without confirmation) and `deny` patterns become `commandDenylist` entries (always require confirmation; the denylist wins when a command is in both). Factory Droid has **no separate `ask` list** — any command not in the allowlist already prompts — so rulesync `ask` rules are dropped. Categories other than `bash` cannot be represented in the command allow/deny model and are skipped, with a `logger.warn` when a skipped category carries a `deny` rule (to surface the gap). rulesync owns the `commandAllowlist` / `commandDenylist` keys (they are replaced from the rulesync output), while every other key in `settings.json` (e.g. `hooks`) is preserved verbatim on round-trip — except the Factory-specific security keys covered by the `factorydroid` override below, which are lifted into that override on import. Importing reads the two lists back into the `bash` category.\n\n> **Factory Droid-only override (`factorydroid` key):** Factory Droid has security controls that do not fit the per-command `allow`/`ask`/`deny` model — the hard-block `commandBlocklist` tier (commands that can **never** run, not even under full autonomy — distinct from an approvable `deny`), plus `networkPolicy` (`allowedIps`), `sandbox` (`enabled`/`mode`/`filesystem`/`network`), `mcpPolicy`, `enableDroidShield`, autonomy settings (`sessionDefaultSettings`, `maxAutonomyLevel`, `interactionMode`), the plugin-bootstrap keys `extraKnownMarketplaces` / `enabledPlugins` (Droid auto-registers those marketplaces and installs those plugins on start — the upstream distribution path for the same artifacts rulesync generates), and the `hooksDisabled` kill-switch. Add a tool-scoped `factorydroid` override to author them: its keys are merged into `settings.json` (the override wins) while the shared `permission` block keeps driving `commandAllowlist`/`commandDenylist`. On **import**, these keys are lifted into the `factorydroid` override — so `commandBlocklist` now round-trips faithfully (its never-runs guarantee is preserved) rather than being collapsed onto an approvable `deny`.\n>\n> ```json\n> {\n> "permission": { "bash": { "git *": "allow" } },\n> "factorydroid": { "commandBlocklist": ["curl *"], "sandbox": { "enabled": true } }\n> }\n> ```\n\nFor Cline CLI, this generates `.cline/command-permissions.json` (project mode only). Cline reads this file via the `CLINE_COMMAND_PERMISSIONS` environment variable; you can wire it up with `export CLINE_COMMAND_PERMISSIONS=$(cat .cline/command-permissions.json)`. The schema is `{ "allow": [...], "deny": [...], "allowRedirects": false }`. Cline only supports shell commands and only `allow`/`deny`. Non-`bash` categories are dropped and rulesync `ask` rules for `bash` are **translated to `deny`** (fail-closed safety, since Cline lacks `ask` semantics); both translation notices are surfaced via a single aggregated `logger.warn` per generation (matching the project convention used by every other permissions translator) so the translation stays visible without tripping CI gates that treat error lines as failures. **The `allow` array is wholesale-replaced by rulesync** — user-added entries inside `allow` are not preserved on regenerate. **The `deny` array is additive** — user-added denies in the existing file are preserved on every generation alongside the rulesync-derived denies (fail-closed standard). The `allowRedirects` field (a single global boolean gating shell redirection operators `>`/`>>`/`<`) can be authored from rulesync via a tool-scoped **`cline` override** — add `"cline": { "allowRedirects": true }` alongside the shared `permission` block. Precedence: the `cline` override wins, otherwise the existing file value is preserved, otherwise it defaults to `false`. On import, a `true` value round-trips back into the `cline` override (the default `false` emits no override). Cline does not have a stable per-user file location for command permissions, so global mode is not supported. If a pattern ends up in **both** `allow` and `deny` (defensive check; not reachable from a single rulesync config), Rulesync emits a warning because Cline does not document a deterministic deny-priority.\n\nFor Zed, this generates the `agent.tool_permissions` object in `.zed/settings.json` (project mode) or `~/.config/zed/settings.json` (global mode — `%APPDATA%\\Zed\\settings.json` on Windows). Each canonical category becomes a key under `agent.tool_permissions.tools.` (tool-name mapping: `bash` → `terminal`, `read` → `read_file`, `edit` → `edit_file`, `write` → `write_file`, `webfetch` → `fetch`, `websearch` → `search_web`; unknown categories, including `mcp::` keys, pass through unchanged). The canonical `*` category is the exception: its catch-all `*` rule sets the top-level `agent.tool_permissions.default` — rung 6 of Zed\'s precedence ladder, and the mechanism Zed documents for MCP tools — rather than an inert `tools["*"]` entry (`*` is not a Zed tool name; a stale `tools["*"]` entry written by an earlier version is cleaned up when the canonical config carries a `*` category, and the `default` imports back as `*: { "*": }`). Pattern-scoped rules in the `*` category have no Zed counterpart and are dropped with a warning. Within every other category, the catch-all `*` pattern sets the per-tool `default`, while specific patterns become `always_allow` / `always_deny` / `always_confirm` entries of the form `{ "pattern": , "case_sensitive": false }`. Action mapping: rulesync `ask` ⇄ Zed `confirm` (`allow`/`deny` are shared). Because Zed matches with regular expressions, patterns are emitted verbatim — author canonical patterns as regexes when targeting Zed. The settings file is shared with the MCP (`context_servers`) and ignore (`private_files`) features, so writes merge non-destructively: unrelated settings, a user-set `agent.tool_permissions.default` (when the canonical config has no `*` category), and any `tools.` entries NOT managed by rulesync are preserved on round-trip. The canonical model has no slot for per-pattern case sensitivity, so rulesync always emits `case_sensitive: false`; a hand-authored `case_sensitive: true` on a rulesync-managed tool is overwritten on the next generate.\n\nFor Qwen Code, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in `.qwen/settings.json` (project mode) or `~/.qwen/settings.json` (global mode). The format mirrors Claude Code\'s: entries are `Bash()`, `Read()`, `Edit()`, `Write()`, `WebFetch()`, `WebSearch()`, `Grep()`, `Glob()`, `Agent()`, etc. Other top-level keys in `settings.json` are preserved on round-trip. Patterns may contain nested parentheses (e.g. `Bash(echo (a))`); Rulesync uses the **last** `)` as the closing delimiter when parsing, so inner parens round-trip. Malformed entries (missing closing paren, trailing characters) emit a warning; for **`deny`** they fall back to the catch-all pattern `*` (fail-closed: broadening a deny is the safer direction), but for **`allow` / `ask`** they are **dropped** rather than broadened — silently turning a narrow user rule into `*` would be a fail-open round-trip. Generation does not create the `.qwen/` directory until `writeAiFiles` runs, so dry-run is side-effect-free.\n\nFor Kimi Code, permissions are global-only and generate `[[permission.rules]]` entries in `~/.kimi-code/config.toml`. Canonical categories map to Kimi tool patterns (`bash` → `Bash`, `read` → `Read`, `write` → `Write`, `edit` → `Edit`, `grep` → `Grep`, `glob` → `Glob`, `websearch` → `WebSearch`, `webfetch` → `FetchURL`, `agent` → `Agent`, and `mcp__…` passes through as the MCP tool name); a `*` canonical pattern emits the bare tool name and a specific pattern emits `Tool(pattern)`. Actions map 1:1 to Kimi\'s `allow` / `ask` / `deny`, and generated rules use `scope = "user"`. Kimi evaluates rules first-match-wins, so Rulesync sorts canonical output fail-closed: all `deny` rules precede `ask`, all `ask` rules precede `allow`, and more-specific patterns precede broader patterns within each action. Kimi does not match MCP tool arguments; an argument-specific MCP `allow`/`ask` is skipped with a warning rather than broadened, while an argument-specific `deny` becomes a whole-tool deny with a warning. The optional `kimi-code.defaultPermissionMode` override writes Kimi\'s top-level `default_permission_mode` (`manual` / `yolo` / `auto`), while `kimi-code.rules` accepts native rules that canonical categories cannot express and emits them first in their authored order. On import, Rulesync preserves the complete ordered rule list under `kimi-code.rules`, including rules that could otherwise fit the shared permission model, so regeneration cannot change Kimi\'s first-match behavior. A `kimi-code.tools` override writes Kimi\'s `[tools] enabled` / `disabled` lists — a separate enforcement layer from `[[permission.rules]]`, since a rule prompts while these remove the tool from every agent in every session. Entries pass through verbatim because the section uses agent-file tool syntax (exact built-in names, `mcp__server__*` globs) rather than the canonical category/pattern shape. Note that Kimi registers `[tools]` in its v2 engine, so today it applies under `kimi web` and experimental `kimi -p` rather than the interactive TUI. Like the MCP defaults, the section merges per key: authoring only `enabled` leaves a hand-written `disabled` list alone, and dropping the override leaves the section as it stands. Values are carried through exactly as written, empty lists included — `enabled = []` is an allowlist admitting _nothing_, the strictest setting there is, while an absent `enabled` means no allowlist at all, so the two are never interchanged. The TOML file is shared with hooks, the MCP timeout defaults and other Kimi settings, so updates merge in place and never delete the file. See the [Kimi Code permission docs](https://moonshotai.github.io/kimi-code/en/configuration/config-files.html).\n\n> **Qwen-only override (`qwencode` key):** Qwen\'s `settings.json` exposes autonomy/sandbox controls with no canonical permission category — under `tools` (`approvalMode` = `plan`/`default`/`auto-edit`/`auto`/`yolo`, `autoAccept`, `sandbox`, `sandboxImage`, `disabled`, `visible` — the deferred-tool startup visibility list, union-merged by Qwen across scopes), `security` (`folderTrust`), and `permissions.autoMode` (the Auto Mode classifier config: `hints.{allow,softDeny,hardDeny}`, `environment`, `classifyAllShell`). Add a tool-scoped `qwencode` override to author them: `qwencode.tools` and `qwencode.security` are shallow-merged into the matching `settings.json` group at the **top level of that group** (an unrelated sibling key such as `tools.core` is preserved, an override key wins, and a nested object the override supplies such as `security.folderTrust` replaces the existing one wholesale rather than being deep-merged), while `qwencode.autoMode` is emitted as `permissions.autoMode` (replacing the existing `autoMode` wholesale) and the shared `permission` block keeps driving the `permissions.allow`/`ask`/`deny` arrays. On import, the documented autonomy keys (`tools.{approvalMode,autoAccept,sandbox,sandboxImage,disabled,visible}`, `security.folderTrust`, and `permissions.autoMode`) round-trip back into the override; other `tools`/`security` keys are left in `settings.json` and not extracted.\n>\n> ```json\n> {\n> "permission": { "bash": { "*": "allow" } },\n> "qwencode": {\n> "tools": { "approvalMode": "auto-edit" },\n> "security": { "folderTrust": { "enabled": true } },\n> "autoMode": { "hints": { "allow": ["Running tests"] }, "classifyAllShell": true }\n> }\n> }\n> ```\n>\n> **Alias overlap:** Qwen\'s `Read` is a meta-tool that also covers grep/glob/list, so canonical `grep`/`glob` rules are emitted as their own `Grep(...)`/`Glob(...)` entries but overlap Qwen\'s `Read` category at runtime; and Qwen folds web search into `web_fetch`, so a canonical `websearch` rule (`WebSearch(...)`) may not correspond to a distinct Qwen tool. `tools.disabled` is a hard whole-tool disable (stronger than `deny`) and is only authorable via the override, not the canonical `deny`.\n\nFor Warp, this generates the command allow/deny regex lists in Warp\'s global user `settings.toml` (**global mode only** — Warp has no project-scoped permissions file). Since Warp promoted file-backed execution profiles to Stable (2026-07-28), the surface runtime enforcement actually reads is the `command_allowlist` / `command_denylist` arrays of the `default` record under `[agents.execution_profiles.]`; rulesync merges the lists into that `default` profile **in place** whenever the collection exists, preserving every other profile key and every other profile ID. The legacy `agent_mode_command_execution_allowlist` / `agent_mode_command_execution_denylist` keys under `[agents.profiles]` are still written for un-migrated installs and old clients — but on a migrated install they are inert (Warp consumes them only once during its one-shot migration). When the `[agents.execution_profiles]` collection does not exist yet, rulesync deliberately does **not** create it: on such an un-migrated install the legacy keys are still live, and creating the collection would mark Warp\'s migration complete early and strand the user\'s other legacy settings. Note that rulesync manages only the `default` profile — if a different execution profile is active in Warp, the generated lists (including `deny` rules) are not enforced until the user switches back to `default`. The settings file path differs per platform: macOS `~/.warp/settings.toml`, Linux `~/.config/warp-terminal/settings.toml`, Windows `%LOCALAPPDATA%\\warp\\Warp\\config\\settings.toml`. Only the `bash` category maps (`allow` → allowlist, `deny` → denylist); Warp matches commands with **regular expressions**, so patterns are emitted verbatim — author canonical `bash` patterns as regexes when targeting Warp (mirrors Zed). Warp has no per-command `ask` list, so `ask` rules are dropped, and non-`bash` categories are skipped (with a warning when they carry `deny` rules). On import, the `default` execution profile\'s lists are preferred (falling back to the legacy keys when no collection exists), and a pattern present in both lists resolves to `deny` (Warp\'s denylist wins). Both blocks are merged into the existing `settings.toml`, preserving other Warp settings, and the file is never deleted. **rulesync owns the command lists** (it is the source of truth): they are replaced from the rulesync config on each `--global` generate, so a manually curated Warp allowlist/denylist not mirrored in `.rulesync/permissions.jsonc` is overwritten — keep command permissions in rulesync (run `rulesync import` first to capture an existing hand-curated list). MCP allow/deny is a separate Warp surface not modeled here. See the [Warp agent profiles & permissions docs](https://docs.warp.dev/agent-platform/capabilities/agent-profiles-permissions/).\n\n> **Warp-only override (`warp` key):** Warp\'s `[agents.profiles]` table also exposes file-read/read-only autonomy knobs that do not fit the per-command `allow`/`ask`/`deny` model — `agent_mode_coding_permissions` (`always_ask_before_reading` / `always_allow_reading` / `allow_reading_specific_files`), `agent_mode_coding_file_read_allowlist` (an array of paths the agent may read), and `agent_mode_execute_readonly_commands` (a boolean auto-executing read-only commands). Add a tool-scoped `warp` override to author them: its keys are merged into `[agents.profiles]` (the override wins) while the shared `permission` block keeps driving the command lists. On **import**, these keys are lifted from `settings.toml` into the `warp` override, so they round-trip faithfully instead of being dropped. These legacy autonomy keys are part of Warp\'s one-shot migration, so on a migrated install they are inert; their execution-profile counterparts are authored through the nested `warp.execution_profile` block instead — `read_files` / `apply_code_diffs` / `execute_commands` / `mcp_permissions` (each `agent_decides` / `always_allow` / `always_ask`), `write_to_pty` (`always_allow` / `always_ask` / `ask_on_first_write`), `ask_user_question` (`never` / `ask_except_in_auto_approve` / `always_ask`), `run_agents` (`never_allow` / `always_allow` / `always_ask`), `computer_use` (`never` / `always_ask` / `always_allow`), `directory_allowlist` (paths readable without approval), and `mcp_allowlist` / `mcp_denylist` (MCP server IDs). Its keys are merged into the `default` record of `[agents.execution_profiles.]` under the same guard as the command lists (only when the collection already exists — creating it would complete Warp\'s migration early; a warning is logged and the block skipped on an un-migrated install), unknown keys pass through verbatim for forward compatibility (export-only: import lifts back exactly the permission keys listed above, while profile-management keys such as `name` or the model overrides never round-trip), and the rulesync-owned `command_allowlist`/`command_denylist` always win. Example:\n>\n> ```json\n> {\n> "permission": { "bash": { "git .*": "allow" } },\n> "warp": {\n> "agent_mode_coding_permissions": "always_allow_reading",\n> "agent_mode_execute_readonly_commands": true,\n> "execution_profile": {\n> "read_files": "always_allow",\n> "directory_allowlist": ["/home/me/projects"],\n> "mcp_denylist": ["untrusted-server"]\n> }\n> }\n> }\n> ```\n>\n> See the [Warp settings reference](https://docs.warp.dev/terminal/settings/all-settings/).\n\nFor the Antigravity IDE, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the committable workspace `.antigravity/settings.json` (**project mode only**). Antigravity 2.0 evaluates these `Deny > Ask > Allow` and uses `action(target)` entries; rulesync maps canonical categories onto the IDE action vocabulary: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the IDE-only `execute_url` / `unsandboxed` actions have no canonical equivalent and pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` file holds other workspace settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. The User-scope settings file is a platform-dependent VS-Code-style path outside rulesync\'s home-relative global model, so **global mode is not supported**; the workspace file is intended to be checked into git. See the [Antigravity permissions docs](https://antigravity.google/docs/permissions).\n\nFor the Antigravity CLI (`agy`), this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the global `~/.gemini/antigravity-cli/settings.json` (**global mode only**). The CLI shares Antigravity 2.0\'s Fine-Grained Permissions Engine with the IDE, so the same `action(target)` vocabulary and `Deny > Ask > Allow` precedence apply: `read` → `read_file`, `edit`/`write` → `write_file`, `bash` → `command`, `webfetch`/`websearch` → `read_url`, `mcp` → `mcp` (the engine-only `execute_url` / `unsandboxed` actions pass through verbatim). Because `edit`/`write` collapse to `write_file` and `webfetch`/`websearch` collapse to `read_url`, importing normalizes back to `write` / `webfetch` (a documented, lossy mapping). The `settings.json` holds other CLI settings, so the `permissions` block is merged in place — entries for unmanaged actions are preserved — and the file is never deleted. Four CLI-only autonomy/sandbox knobs outside the allow/ask/deny arrays can be authored (and round-trip) through an optional `antigravity-cli` override block in `.rulesync/permissions.jsonc`: `toolPermission` (the global autonomy preset — `request-review` (default) / `proceed-in-sandbox` / `always-proceed` / `strict`), `enableTerminalSandbox` (a boolean confining agent-run commands to OS containment), `artifactReviewPolicy` (whether the agent\'s artifact changes are gated on a review prompt — `asks-for-review` (default) / `agent-decides` / `always-proceed`) and `allowNonWorkspaceAccess` (a boolean, off by default, letting the agent read or write files outside the active workspace roots). Antigravity applies the allow/deny lists as per-rule exceptions to the preset at runtime, so rulesync authors these keys verbatim as top-level siblings of `permissions` with no precedence modeling. This override is **CLI-only** — the Antigravity IDE exposes the same concepts through a GUI with no documented JSON schema, so it does not apply to `antigravity-ide`. Example: `{ "permission": { … }, "antigravity-cli": { "toolPermission": "strict", "enableTerminalSandbox": true, "artifactReviewPolicy": "agent-decides", "allowNonWorkspaceAccess": false } }`. Verified against the [Antigravity CLI reference](https://antigravity.google/docs/cli/reference), [sandbox docs](https://antigravity.google/docs/cli/sandbox) and [settings reference](https://antigravity.google/docs/cli/settings). See the [Antigravity CLI permissions docs](https://antigravity.google/docs/cli-permissions).\n\nFor Rovo Dev CLI, this generates the `toolPermissions` block of `config.yml` — the global `~/.rovodev/config.yml`, and in project mode the repo-committed `.rovodev/config.yml` that the [Bitbucket Cloud Agentic Pipelines guide](https://support.atlassian.com/bitbucket-cloud/docs/rovo-dev-advanced-agentic-configuration/) documents (referenced from `bitbucket-pipelines.yml` via `config.path`, or the `--config-file` CLI flag); the project file is deliberately **not** gitignored, since committing it is how Rovo Dev permissions get enforced in CI. Rovo Dev\'s three levels (`allow`/`ask`/`deny`) are an exact 1:1 with rulesync\'s canonical actions, so action values pass through verbatim. The `bash` category maps the catch-all `*` pattern to `bash.default` and every other pattern to a `bash.commands[]` entry `{ command: , permission }` (Rovo Dev matches commands as regexes, so author `bash` patterns accordingly). The `read` category maps to the inspection tools (`open_files`, `expand_code_chunks`, `expand_folder`, `grep`) and `edit`/`write` to the mutation tools (`find_and_replace_code`, `create_file`, `delete_file`, `move_file`), written under **`toolPermissions.tools`** — the depth Rovo Dev documents. (Earlier Rulesync versions wrote them one level up, directly under `toolPermissions`, where Rovo Dev ignores them; import still reads that legacy shape as a fallback for keys the nested block says nothing about, so an old file is not lost, and a regenerate deletes the stale copies.) Because these per-tool keys hold a single level (no per-pattern rules), only the catch-all `*` of each category sets the level. Rovo Dev rewrites a single tool key when the user answers "always allow" to one prompt, so the four keys of a category can disagree; import collapses them back onto one catch-all by taking the strictest level (`deny` > `ask` > `allow`) rather than whichever key is read last. Rovo Dev\'s planning and Atlassian tools split the same way, so they ride the same two categories rather than getting one of their own: `read` also reaches `getJiraIssue` and `getConfluencePage`, and `edit`/`write` also reach `createJiraIssue`, `updateJiraIssue`, `createConfluencePage`, `updateConfluencePage` and `createTechnicalPlan` (grouped with the mutating tools because it is the planning tool that produces an artifact rather than reading one). Bear that in mind when authoring: an `edit: deny` reaches Jira and Confluence, not just the working tree. Because `edit` and `write` both map onto the same mutation tools, a conflicting catch-all between them cannot be represented; the stricter of the two levels is kept — the same `deny` > `ask` > `allow` rule import uses — and a warning is logged. Non-catch-all `allow` paths in those categories are surfaced as `allowedExternalPaths` so explicit grants are not dropped; non-`allow` non-catch-all rules cannot be expressed per-path and are skipped with a warning. Categories without a clean Rovo Dev target (e.g. `webfetch`) are skipped with a warning. `config.yml` holds all of Rovo Dev\'s settings (`agent`, `sessions`, `mcp`, etc.), so the `toolPermissions` block is merged in place — every other top-level key is preserved, as is any key inside `toolPermissions` that Rulesync does not manage — including tools inside `toolPermissions.tools` that no canonical category maps to. On **import**, a tool key the file is silent about counts as the implicit fallback level (`toolPermissions.default`, or Rovo Dev\'s own `ask`) rather than as absent, and the category still collapses to the strictest of the set. That matters because Rovo Dev writes a single key when the user answers "always allow" to one prompt: without the fallback, one such answer about `create_file` would import as a blanket `edit: allow`, and the next generate would hand that grant to every other tool of the category — Jira and Confluence writes included. A category the file says nothing about at all is still skipped rather than invented.\n\n**Migration note.** `toolPermissions.default` and the seven planning/Atlassian keys became Rulesync-owned in the release that added them. Ownership means the first generate after upgrading removes a hand-written value for one of them unless `.rulesync/permissions.*` produces it — a hand-written `tools.createJiraIssue: deny` or `default: deny` with no matching rule in the rulesync source is dropped (with a warning naming each key), falling back to Rovo Dev\'s `ask`. Run `rulesync import --targets rovodev --features permissions` before the first generate to carry those values into the rulesync source.\n\nThe canonical all-tools category `*` maps to `toolPermissions.default`, the level Rovo Dev falls back to for any tool with no more specific setting (Rovo Dev\'s own default is `ask`) — derived from its catch-all exactly as `bash.default` is derived from `bash`\'s, and round-tripped back on import. The default is a single level, so a pattern rule inside the `*` category has no counterpart and is skipped with a warning. The keys Rulesync does manage (`default`, `bash`, `allowedExternalPaths`, and the per-tool keys above) are owned rather than merged: each generate rewrites them from `.rulesync/permissions.*`, so removing a rule there removes it from `config.yml` too (a source stating no rule at all clears them; one whose rules simply have no Rovo Dev counterpart keeps the block\'s restrictions but strips its grants — an `allow` there is normally a leftover of an earlier generate, and dropping one falls back to Rovo Dev\'s stricter default, whereas clearing the whole block would relax every level), logging a warning naming each owned key it removes — per-tool levels and `allowedExternalPaths` are written from inside a Rovo Dev session too, by an "always allow" prompt answer and the `/directories` command, and a hand-edit to one of those keys — including a path added with the in-session `/directories` command, which writes to `allowedExternalPaths` — is replaced on the next generate (values only — YAML comments and formatting in the existing file are not retained on rewrite) — and the file is never deleted. See the [Rovo Dev CLI settings](https://support.atlassian.com/rovo/docs/manage-rovo-dev-cli-settings/) and [tool permissions](https://support.atlassian.com/rovo/docs/use-tools-in-rovo-dev-cli/) docs.\n\nFor Goose, this generates the `user` block of the global `~/.config/goose/permission.yaml` (**global mode only** — Goose persists per-tool permission overrides only under the home directory and has no project-scoped permissions file). Goose stores permissions as a YAML map of mode key → `{ always_allow, ask_before, never_allow }`, where each field is a list of tool-name strings; rulesync writes the user-set decisions under the `user` key. Action mapping is a 1:1: `allow` → `always_allow`, `ask` → `ask_before`, `deny` → `never_allow`. Tool-name mapping: `bash` → `developer__shell`, `edit` → `developer__text_editor`; every other category passes through verbatim as the Goose tool name (so namespaced tools like `developer__text_editor` or `developer__image_processor` round-trip). Because Goose permission lists hold **whole tool names** rather than per-command/per-path globs, only a category\'s catch-all `*` pattern is representable — non-catch-all patterns are skipped with a warning. `write` collapses onto `developer__text_editor` too, so a conflicting `edit`/`write` catch-all cannot be represented; `edit` takes precedence and a warning is logged. The `permission.yaml` file is merged in place: the `user` block is owned by rulesync, while every other top-level key (notably the `smart_approve` LLM-decision cache) is preserved, and the file is never deleted. See the [Goose tool permissions docs](https://goose-docs.ai/docs/guides/managing-tools/tool-permissions/).\n\nFor the Grok Build CLI (`grokcli`), this generates Grok\'s Claude-style `[permission]` rule arrays — `allow` / `deny` / `ask` — in the project `./.grok/config.toml` (project mode) or the user `~/.grok/config.toml` (global mode, via `--global`). Grok documents that "Project configs are limited to MCP servers, plugins, and permission rules, not full user configs" ([settings docs](https://docs.x.ai/build/settings)), so the fine-grained `[permission]` rules are valid at both scopes. Each canonical `permission..` becomes a Grok entry bucketed into the matching array: `bash`→`Bash`, `read`→`Read`, `edit`→`Edit`, `grep`→`Grep`, `webfetch`→`WebFetch`, and `mcp____`→`MCPTool(__)`; a `*` pattern emits the bare tool name (e.g. `Bash`) and a concrete pattern emits `Tool(pattern)` (e.g. `Bash(git *)`). `write` collapses onto `Edit` (Grok has no separate `Write` tool — a documented lossy mapping), and categories with no Grok tool (`websearch`, `glob`, `notebookedit`, `agent`) are skipped, with a warning when a skipped category carries a `deny` rule. Grok evaluates the arrays with precedence `deny > ask > allow`, which import mirrors (a tool listed in multiple arrays resolves to the strictest action). The coarse `[ui] permission_mode` toggle (`"ask"` / `"always-approve"`) is still written as a backward-compatible fallback for older Grok versions: `always-approve` when the config is pure-`allow`, otherwise `ask` (conservative — never `always-approve` while any `deny`/`ask` rule exists, so it never contradicts the fine-grained arrays). On import, the `[permission]` arrays are parsed back into canonical categories when present; only when no `[permission]` section exists do we fall back to the coarse mode (`always-approve` ⇄ `bash: { "*": "allow" }`, `ask`/unset ⇄ `bash: { "*": "ask" }`). `config.toml` is shared with the MCP feature, so rulesync owns the `[permission]` `allow`/`deny`/`ask` arrays and `[ui] permission_mode` while every other key (e.g. `[mcp_servers]`, verbose `[permission] rules`, `[sandbox]`) is preserved, and the file is never deleted. See the [Grok CLI settings reference](https://docs.x.ai/build/settings/reference) and [modes docs](https://docs.x.ai/build/modes-and-commands).\n\nFor Vibe (mistral-vibe), this generates per-tool `[tools.]` tables in the shared `.vibe/config.toml` (project mode) or `~/.vibe/config.toml` (global mode). Tool-name mapping: `bash` → `bash`, `read` → `read_file`, `edit` → `edit`, `write` → `write_file`, `webfetch` → `web_fetch`, `websearch` → `web_search`, `grep` → `grep`, `agent` → `task`. These are Vibe\'s builtin tool names (`BaseTool.get_name()`, the snake_case of each tool class); `edit` and `write_file` are distinct tools — `write_file` has been create-only since v2.14.0 — so the two canonical categories no longer collapse onto one name. **Migration:** a `config.toml` written by an earlier Rulesync may still carry `write_file` entries derived from the `edit` category, or inert `[tools.fetch]` / `[tools.search_web]` / `[tools.agent]` blocks. Rulesync only rewrites the names it now emits, so remove those stale entries by hand — a leftover `disabled_tools = ["write_file"]` keeps Vibe\'s `write_file` disabled even though no canonical rule asks for it, and inert `[tools.glob]` / `[tools.notebookedit]` tables an earlier Rulesync emitted for tools Vibe does not have stay on disk until removed by hand (new generates skip those categories instead of rewriting them). Within a category, the catch-all `*` pattern sets the per-tool `permission` (`allow` → `always`, `ask` → `ask`, `deny` → `never`); a wildcard deny additionally adds the tool to the top-level `disabled_tools` filter. A wildcard allow deliberately does **not** touch the top-level `enabled_tools` key: upstream treats it as an **exclusive** allowlist (“if set, only these tools will be active”), so expressing allows through it — as earlier Rulesync versions did — silently switched off every other builtin and MCP tool; the per-tool `permission = "always"` entry carries the allow completely, and a regenerate now removes the exclusive entries an earlier version wrote for the tools it configures; specific patterns become **`allowlist` / `denylist`** entries — these are the keys Vibe\'s permission engine actually reads (`BaseToolConfig`), so the legacy `allow` / `deny` keys are dropped on generate (still honored as a fallback on import). Vibe has no per-pattern `ask`, so pattern-level `ask` rules are skipped with a warning. A canonical category with no Vibe builtin tool at all (e.g. `glob`, `notebookedit`) is likewise skipped with a warning instead of emitting an inert `[tools.]` table — a `deny` written there would look applied while Vibe ignores it. Unknown `[tools.*]` tables already on disk still round-trip untouched. The `config.toml` file is shared with the MCP feature, so writes merge non-destructively and the file is never deleted. See [mistral-vibe](https://github.com/mistralai/mistral-vibe) (`vibe/core/tools/base.py`).\n\n> **Vibe-only override (`vibe` key):** Vibe\'s `BaseToolConfig` also carries a `sensitive_patterns` list — patterns that escalate to **ASK even when the base permission is ALWAYS** (allow). The canonical model can only set a pattern to a single `allow`/`ask`/`deny`, so an "allow by default but ask on these patterns" escalation cannot be expressed in the shared block. Add a tool-scoped `vibe` override to author it: `vibe.permission..sensitive_patterns` carries the list per canonical category (e.g. `bash`, `edit`), while the shared `permission` block still sets the base permission and allow/deny lists. On import, a tool\'s `sensitive_patterns` round-trips back into the `vibe` override (the base allow stays in the shared block). rulesync owns the list for any category named in the override (a present list is set, an empty one clears it); categories not named keep whatever the existing `config.toml` had. The override also carries `vibe.enabled_tools` — the only way to author Vibe\'s top-level **exclusive** allowlist. The list is written verbatim in Vibe\'s tool-name vocabulary (declaring it, even empty, makes rulesync own the whole key), and on import a non-empty `enabled_tools` is lifted back into the override rather than being misread as a set of `"*": "allow"` grants. Note the `config.toml` scope semantics: Vibe reads exactly **one** config file — the trusted project `.vibe/config.toml` when present, otherwise `~/.vibe/config.toml` (a fallback, not a merge; single code path since v2.22.0) — so a `--global` run warns when the current project has its own `config.toml`, which shadows the global one for the `mcp` and `permissions` surfaces (rules, hooks, agents and skills genuinely combine scopes).\n>\n> ```json\n> {\n> "permission": { "bash": { "*": "allow" } },\n> "vibe": { "permission": { "bash": { "sensitive_patterns": ["rm *", "sudo *"] } } }\n> }\n> ```\n\nFor Takt, this generates the `default_permission_mode` under `provider_profiles.` in the shared `.takt/config.yaml` (project mode) or `~/.takt/config.yaml` (global mode). Takt does not have per-tool / per-pattern rules; tool gating is a single coarse mode per provider profile, ordered `readonly` < `edit` < `full` (`readonly` may only read, `edit` may also edit/write files, `full` may also run shell commands). The active provider is named by the top-level `provider:` key (defaulting to `claude`). The mapping is therefore **lossy**: on generate, a single mode is derived with this precedence — (1) any `deny` rule anywhere ⇒ `readonly` (conservative — keep the narrowest mode whenever the user expressed any restriction); (2) else any `edit`/`write` category `allow` rule ⇒ `edit`; (3) else any `bash` category `allow` rule ⇒ `full`; (4) else ⇒ `readonly` (safe default). On import, `full` ⇄ `bash: { "*": "allow" }`, `edit` ⇄ `edit: { "*": "allow" }`, and `readonly` (or an unset/unknown mode) ⇄ `bash: { "*": "deny" }`. `config.yaml` is shared with other Takt settings, so the mode is merged in place — every other provider profile and all other top-level keys are preserved — and the file is never deleted. Takt\'s default-deny **workflow security policies** — `workflow_arpeggio` (`custom_data_source_modules`, `custom_merge_inline_js`, `custom_merge_files`), `workflow_runtime_prepare.custom_scripts`, `workflow_command_gates.custom_scripts`, `sync_conflict_resolver.auto_approve_tools`, and the `allow_git_hooks` / `allow_git_filters` booleans — have no canonical permission category, so they are authored through the `takt` override block of `.rulesync/permissions.*` and round-trip on import. Each admits one class of user-supplied code, so only the exact shapes Takt itself accepts are written: a sub-key Takt does not declare is dropped with a warning rather than passed through, since Takt\'s schemas are strict and reject the whole file on an unknown key, while a value of the wrong type fails when `.rulesync/permissions.*` is read. Removing one of these keys from `config.yaml` because the source no longer states it is warned about too — including a key put there by hand, which owning them implies. Deleting `.rulesync/permissions.*` altogether is different: the feature has no source to generate from, so nothing runs and whatever is in `config.yaml` stays. These keys are also authoritative rather than merged — revoking one in `.rulesync/permissions.*` removes it from `config.yaml`, instead of leaving the capability switched on. `workflow_mcp_servers` stays with the MCP feature, which derives it from the transports in use.\n\nTwo Takt-specific surfaces with no canonical category can be authored (and round-trip) through an optional `takt` override block in `.rulesync/permissions.jsonc`: `step_permission_overrides` (a per-workflow-step map `` ⇒ `readonly`/`edit`/`full`, written inside the active provider profile and layered by Takt on top of `default_permission_mode`) and `provider_options` (a top-level, per-provider table of sandbox/network knobs orthogonal to the mode, e.g. `codex.network_access`, `claude.sandbox.allow_unsandboxed_commands`, `opencode.allowed_tools`). Example: `{ "permission": { … }, "takt": { "step_permission_overrides": { "ai_review": "readonly" }, "provider_options": { "codex": { "network_access": true } } } }`. Note the workflow-step `required_permission_mode` floor is a field of the **workflow YAML**, not `config.yaml`, so it is intentionally out of scope (Takt\'s config loader hard-rejects unknown top-level keys). See the [Takt configuration docs](https://github.com/nrslib/takt/blob/main/docs/configuration.md).\n\nFor Amp, this writes to the shared `.amp/settings.json` (project mode) or `~/.config/amp/settings.json` (global mode), using **two** permission surfaces. In rulesync\'s canonical model the category name **is** the Amp tool name. A **whole-tool deny** (pattern `*`) is written to the bare `amp.tools.disable` array (the tool name is pushed verbatim, preserving `builtin:` prefixes and the `*` glob) for backwards compatibility. Every **lossy** case is written to the ordered `amp.permissions` array instead of being dropped: an **argument-specific deny** (pattern `!== "*"`) becomes `{ tool, action: "reject", matches: { cmd: } }`, and every `allow` / `ask` rule becomes `{ tool, action, matches?: { cmd } }` (the `matches` object is omitted for the `*` catch-all). Amp evaluates `amp.permissions` **first-match-wins**, so generated entries are ordered deterministically and fail-closed: sorted by tool name, then entries **with** `matches.cmd` (more specific) before catch-alls, then by action priority **`reject` < `ask` < `allow`**, then by `cmd`. `amp.permissions` is Amp\'s documented **legacy / backwards-compatibility** surface — it remains functional and is the only place to express `allow`/`ask` and argument-specific `reject` rules. **Ownership:** rulesync OWNS and wholesale-replaces the `allow`/`ask`/`reject` entries on every generate, but **preserves any existing `action: "delegate"` entry** (rulesync\'s canonical model has no `delegate` equivalent); preserved `delegate` entries are placed **after** the rulesync-generated entries (so the regenerated rules take precedence under first-match-wins). On **import**, both keys are read and merged into one canonical config: `amp.tools.disable[tool]` → `{ tool: { "*": "deny" } }`, and each `amp.permissions` entry → `{ tool: { (matches?.cmd ?? "*"): mapped } }` (`reject` → `deny`, `allow` → `allow`, `ask` → `ask`; `delegate` is skipped). When both sources target the same tool+pattern, the **most restrictive action wins** (`deny` > `ask` > `allow`). The settings file is shared with the MCP feature (`amp.mcpServers`), so all other keys are preserved on round-trip and the file is never deleted. Tool names and `cmd` patterns that are prototype-pollution keys (`__proto__`, `constructor`, `prototype`) are skipped defensively.\n\nAmp shapes with no canonical category are authored (and round-trip) through an optional `amp` override block in `.rulesync/permissions.jsonc`: `permissions` — extra `amp.permissions` entries with non-`cmd` matchers (`path`/`url`/`query`/…), regex/array match values, `context` (`thread`/`subagent`), `delegate` (+`to`), or `reject` (+`message`), appended **after** the canonical-generated entries (so generated allow/ask/reject rules take precedence under first-match-wins, with authored entries as later fallbacks); `mcpPermissions` — Amp\'s `amp.mcpPermissions` array; `guardedFiles` — `amp.guardedFiles.allowlist` (globs allowed without confirmation); and `dangerouslyAllowAll` — `amp.dangerouslyAllowAll`. When the override authors `permissions` it becomes the source of truth for the extra entries; otherwise any hand-authored `delegate` entry in the existing file is preserved. On import, `amp.permissions` entries that are **not** canonical-expressible (non-`cmd` matcher, `delegate`, `reject`+`message`, `context`) are lifted verbatim into `amp.permissions` of the override rather than dropped. Example: `{ "permission": { … }, "amp": { "dangerouslyAllowAll": false, "guardedFiles": { "allowlist": ["docs/**"] }, "permissions": [{ "tool": "Bash", "action": "delegate", "to": "approve.sh" }] } }`. See the [Amp manual](https://ampcode.com/manual).\n\nFor JetBrains Junie CLI, this generates the Action Allowlist `rules` object in `~/.junie/allowlist.json` (**global mode only** — Junie CLI resolves exactly one allowlist path under its home directory and never reads a project-scope `.junie/allowlist.json`; verified against release `2383.10`). Junie evaluates the allowlist top-to-bottom (first match wins) and groups rules into buckets, onto which rulesync categories map: `bash` → `executables`, `edit`/`write` → `fileEditing`, `read` → `readOutsideProject`, `mcp` → `mcpTools`. Every rule group is written as Junie\'s `AllowListRuleSet` **object** — `{ "default"?: "allow"|"ask", "rules": [ … ] }` — never a bare array: Junie\'s parser rejects the array form for the **whole file** and then discards and overwrites `allowlist.json`, so the shape matters. Earlier rulesync versions emitted the array form; it is still tolerated on import, but only the object form is generated. Each rule carries an `action` plus either a literal `prefix` (matches commands that start with it) or a glob `pattern` (`*`, `**`, `?`, `[abc]`, `[!abc]`); rulesync emits `pattern` when the canonical pattern contains a glob metacharacter (`*`, `?`, `[`) and `prefix` otherwise. Junie accepts only `allow` and `ask` as actions — there is **no `deny`** (a `deny` fails the whole-file parse) — so a canonical `deny` is downgraded to the nearest valid action, `ask` (which still withholds auto-approval), with a warning (`allow`/`ask` map 1:1). Categories Junie cannot represent (e.g. `webfetch`, `websearch`) are skipped with a warning when they carry rules. rulesync **owns each mapped group\'s rule list** (replaced on each generate), while a per-group `default` and the whole `readSecretFile` group — which restricts what Junie may read — are preserved from the existing file when not authored via the `junie` override below. Because `edit`/`write` both collapse onto `fileEditing`, importing normalizes back to `edit` (a documented, lossy mapping). The `allowlist.json` file is never deleted. See the [Junie Action Allowlist docs](https://junie.jetbrains.com/docs/action-allowlist-junie-cli.html).\n\n> **Junie-only override (`junie` key):** Junie\'s `allowlist.json` has settings with no canonical per-glob slot — the top-level autonomy knobs `allowReadonlyCommands` (a boolean auto-allowing read-only commands) and `defaultBehavior` (the fallback action when no rule matches; an `allow`/`ask` enum — Junie\'s `AllowListDecision` accepts nothing else, and an invalid value fails the whole-file parse), plus two group-shaped settings: `readSecretFile` (the fifth rule group, restricting reads of secret files — canonical `read` is already taken by `readOutsideProject`, so this group is authored whole as `{ "default"?, "rules": [ … ] }`) and `ruleDefaults` (each mapped group\'s own fallback action, e.g. `{ "executables": "ask" }`). Add a tool-scoped `junie` override to author them: the scalar knobs are merged onto the top level of `allowlist.json` (the override wins) while the shared `permission` block keeps driving the mapped groups\' rule lists, and the group-shaped settings land inside the `rules` object. On **import**, all of these are lifted from `allowlist.json` into the `junie` override, so they are authorable and portable instead of only round-trip-preserved. Any other unmodeled top-level key is preserved verbatim. Example:\n>\n> ```json\n> {\n> "permission": { "bash": { "git ": "allow" } },\n> "junie": {\n> "allowReadonlyCommands": true,\n> "defaultBehavior": "ask",\n> "ruleDefaults": { "executables": "ask" },\n> "readSecretFile": { "rules": [{ "pattern": "**/.env", "action": "ask" }] }\n> }\n> }\n> ```\n\nFor Reasonix, this generates `permissions.allow`, `permissions.ask`, and `permissions.deny` arrays in the `[permissions]` table of the shared `reasonix.toml` (project mode) or `~/.reasonix/config.toml` (global mode) — the same TOML file the MCP feature\'s `[[plugins]]` array-of-tables lives in. The rule syntax mirrors Claude Code\'s: entries are `Bash()`, `Read()`, `Edit()`, `Write()`, `WebFetch()`, `WebSearch()`, `Grep()`, `Glob()`, `NotebookEdit()`, `Agent()`, etc. (Reasonix\'s SPEC.md documents these as "Claude Code-style" families; `agent` → `Agent` is the one lower-confidence mapping, since Reasonix\'s own delegation tool is internally named `task`). `[permissions].mode` (the writer fallback: `ask`/`allow`/`deny`) has no canonical rulesync equivalent and is preserved untouched. The TOML file is shared with the MCP feature, so writes only replace the `permissions` table — every other table (`[[plugins]]`, `[agent]`, `[ui]`, …) is preserved on round-trip, and the file is never deleted. See [SPEC.md §3.7 Permissions](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md).\n\n> **Reasonix-only override (`reasonix` key):** Reasonix has security axes orthogonal to per-tool allow/ask/deny with no canonical category — the `[sandbox]` enforcement table (`workspace_root`, `allow_write`, `forbid_read`, `bash` = `enforce`/`off`, `network`) and the plan-mode read-only command list under `[agent]` (`plan_mode_read_only_commands`, which upstream keeps for legacy compatibility only — Plan bash goes through Permissions now). Its sibling `plan_mode_allowed_tools` left the documented config surface in v1.17.18: an existing value is still lifted out of `[agent]` on import, so it does not vanish from an imported config, but whenever the override writes `[agent]` the key is removed from the file with a warning — including a value already there, since leaving that one alone would mean narrowing the list is the one edit that never lands. Add a tool-scoped `reasonix` override to author them: `reasonix.sandbox` and `reasonix.agent` are shallow-merged into the matching `reasonix.toml` table at its top level (override keys win, unrelated sibling keys such as `[agent].model` are preserved), while the shared `permission` block keeps driving `[permissions].allow`/`ask`/`deny`. The override also carries `rawAllow`/`rawAsk`/`rawDeny` — verbatim `[permissions]` entries merged into the generated arrays untranslated. They exist for the first-class `Bash=` exact-command form (SPEC §3.7, v1.18.0: metacharacters in the literal are ordinary characters and only the identical complete command matches), which the canonical tool→pattern→action shape cannot express and which is the only way to pre-authorize dynamic or nested Bash in headless `reasonix run` short of YOLO. Exact entries already in `reasonix.toml` — Reasonix writes them itself as remembered approvals — are always preserved on generate, even for tools the shared block manages. On import, the whole `[sandbox]` table round-trips (it is a dedicated security surface), only the plan-mode keys are lifted from `[agent]`, and exact `Tool=` entries are lifted into `rawAllow`/`rawAsk`/`rawDeny` instead of masquerading as a bogus tool category in the shared block.\n>\n> ```json\n> {\n> "permission": { "bash": { "git status*": "allow" } },\n> "reasonix": {\n> "sandbox": { "bash": "enforce", "network": false },\n> "agent": { "plan_mode_read_only_commands": ["gh pr diff"] }\n> }\n> }\n> ```\n>\n> The retired `[[plugins]].trusted_read_only_tools` MCP read-only trust list is per-plugin (an array-of-tables shared with the MCP feature) and is not covered by this override.\n\n> **Note: Interaction with deprecated ignore feature.** Both the ignore feature and the permissions feature can manage `Read` tool deny entries in `.claude/settings.json`. When both features configure the `Read` tool, the **permissions feature takes precedence** and a warning is emitted. Migrate the ignore patterns to `read` deny rules in `.rulesync/permissions.jsonc`, then remove `ignore` from the project features and delete the obsolete ignore source.\n', "reference/mcp-server": '# Rulesync MCP Server\n\nRulesync provides an MCP (Model Context Protocol) server that enables AI agents to manage your Rulesync files. This allows AI agents to discover, read, create, update, and delete files dynamically.\n\n> [!NOTE]\n> The MCP server exposes the only one tool to minimize your agent\'s token usage. Approximately less than 1k tokens for the tool definition.\n\n## Supported Features and Operations\n\nThe single `rulesyncTool` multiplexes by `feature` and `operation`:\n\n- `rule`, `command`, `subagent`, `skill`: `list`, `get`, `put`, `delete`\n- `ignore`, `mcp`, `permissions`, `hooks`: `get`, `put`, `delete`\n- `generate`: `run`\n- `import`: `run`\n- `convert`: `run`\n\nThe `permissions` feature operates on `.rulesync/permissions.jsonc` and the `hooks` feature operates on `.rulesync/hooks.jsonc`. Both accept a `content` string (valid JSONC) on `put`.\n\n### `convert` / `run` options\n\nWhen invoking `feature: "convert"` with `operation: "run"`, pass `convertOptions` with the following shape:\n\n| Option | Type | Required | Description |\n| ---------- | ---------- | -------- | ---------------------------------------------------------------------------------- |\n| `from` | `string` | Yes | Source tool name (e.g. `"claudecode"`). Must be a valid `ToolTarget`. |\n| `to` | `string[]` | Yes | One or more destination tool names. Must not be empty and must not include `from`. |\n| `features` | `string[]` | No | Features to convert (e.g. `["rules", "commands"]`). Defaults to `["*"]`. |\n| `global` | `boolean` | No | Convert global (user-scope) configurations. Defaults to `false`. |\n| `dryRun` | `boolean` | No | Preview changes without writing files. Defaults to `false`. |\n\n## Usage\n\n### Starting the MCP Server\n\n```bash\nrulesync mcp\n```\n\nThis starts an MCP server using stdio transport that AI agents can communicate with.\n\n### Configuration\n\nAdd the Rulesync MCP server to your `.rulesync/mcp.jsonc`:\n\n```json\n{\n "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json",\n "mcpServers": {\n "rulesync-mcp": {\n "type": "stdio",\n "command": "npx",\n "args": ["-y", "rulesync", "mcp"],\n "env": {}\n }\n }\n}\n```\n', "reference/supported-tools":