{ "updated": "2026-10-18", "firstPublished": "2026-09-29", "levels": { "N": "Native", "C": "Compatible: reads another host's format, or available via config", "P": "Partial: opt-in, limited to some interfaces, or reduced", "-": "None", "?": "Unverified" }, "areas": [ { "id": "surfaces", "label": "Interfaces & headless" }, { "id": "instructions", "label": "Instructions & rules" }, { "id": "skills", "label": "Skills" }, { "id": "agents", "label": "Agent profiles & commands" }, { "id": "hooks", "label": "Hooks" }, { "id": "policy", "label": "Policy, sandbox & ignore" }, { "id": "mcp", "label": "MCP (tool servers)" }, { "id": "intel", "label": "Code intelligence & memory" }, { "id": "plugins", "label": "Packages & distribution" } ], "capabilities": [ { "id": "surface.cli", "area": "surfaces", "label": "Terminal CLI / TUI", "tier": "-", "strategy": "Not a portability concern; note which interface you tested on, because features differ between them." }, { "id": "surface.ide", "area": "surfaces", "label": "IDE (editor or extension)", "tier": "-", "strategy": "Test IDE and CLI separately; Copilot VS Code Local and Copilot CLI differ materially." }, { "id": "surface.cloud", "area": "surfaces", "label": "Cloud / background agent", "tier": "-", "strategy": "Cloud agents run the repo harness remotely; anything that depends on user-level config will be missing." }, { "id": "headless.run", "area": "surfaces", "label": "Headless run from a script (prompt in, exit)", "tier": "P0", "strategy": "Per-host eval adapter around the headless command; one CI job can test a tool in every host." }, { "id": "headless.json", "area": "surfaces", "label": "Headless with machine-readable (JSON) output", "tier": "P0", "strategy": "Parse JSON output in the eval adapter to record skill activation and outcomes." }, { "id": "instr.agents-md", "area": "instructions", "label": "Reads AGENTS.md", "tier": "P1", "strategy": "Author AGENTS.md as the source of truth; add one line of glue where a host needs it." }, { "id": "instr.claude-md", "area": "instructions", "label": "Reads CLAUDE.md", "tier": "P1", "strategy": "CLAUDE.md = '@AGENTS.md' plus Claude-only notes; avoids double loading in hosts that cross-read." }, { "id": "instr.own-file", "area": "instructions", "label": "Own always-on instruction file (host-specific name)", "tier": "P2", "strategy": "Generate a one-line wrapper pointing at AGENTS.md rather than duplicating content." }, { "id": "instr.nested", "area": "instructions", "label": "Per-folder (nested) instruction files", "tier": "P1", "strategy": "Nested AGENTS.md plus generated wrappers; check each host's loading direction." }, { "id": "instr.imports", "area": "instructions", "label": "Inline @-imports of other files", "tier": "P3", "strategy": "Summarise inline and link the detail; never depend on inlining." }, { "id": "rules.glob", "area": "instructions", "label": "Triggered rules scoped by file glob", "tier": "P2", "strategy": "One neutral rule source generated per host; fold into nested AGENTS.md where there are no rules." }, { "id": "rules.description", "area": "instructions", "label": "Rules activated by description (model decides)", "tier": "P3", "strategy": "Prefer a skill: same activation model, portable format." }, { "id": "skills.agents-dir", "area": "skills", "label": "Skills in .agents/skills", "tier": "P1", "strategy": "Canonical .agents/skills; deliver .claude/skills as a link or copy for Claude Code." }, { "id": "skills.claude-dir", "area": "skills", "label": "Skills in .claude/skills", "tier": "P1", "strategy": "Second delivery folder; watch for double discovery in hosts that read both." }, { "id": "skills.spec", "area": "skills", "label": "Agent Skills spec (SKILL.md, progressive disclosure)", "tier": "P1", "strategy": "Six spec fields only, actor-neutral wording, lint in CI because invalid skills fail silently." }, { "id": "skills.extras", "area": "skills", "label": "Host-specific skill frontmatter extensions", "tier": "P3", "strategy": "Extras are P3; generate them per target, never in the canonical SKILL.md." }, { "id": "commands.format", "area": "agents", "label": "User commands as their own format", "tier": "P3", "strategy": "Author as skills; generate command files only for hosts that still need them." }, { "id": "agents.profiles", "area": "agents", "label": "Agent profiles (named sub-agents)", "tier": "P2", "strategy": "Neutral agent-profile YAML fed to generators." }, { "id": "agents.tool-limits", "area": "agents", "label": "Agent profile can restrict its tools", "tier": "P2", "strategy": "Generators warn, never silently widen, when a target can't express tool limits." }, { "id": "agents.cross-read", "area": "agents", "label": "Reads another host's agent-profile folder", "tier": "P2", "strategy": "Useful fallback, but generate native files so behaviour is explicit." }, { "id": "hooks.shell", "area": "hooks", "label": "Shell-command hooks (event count in note)", "tier": "P2", "strategy": "One hook core plus a thin adapter per host." }, { "id": "hooks.session-start", "area": "hooks", "label": "Event: session.start", "tier": "P2", "strategy": "Part of the portable four-event coverage." }, { "id": "hooks.tool-before", "area": "hooks", "label": "Event: tool.before", "tier": "P2", "strategy": "Part of the portable four-event coverage. Re-filter inside the core, because matchers aren't portable." }, { "id": "hooks.tool-after", "area": "hooks", "label": "Event: tool.after", "tier": "P2", "strategy": "Part of the portable four-event coverage." }, { "id": "hooks.agent-stop", "area": "hooks", "label": "Event: agent.stop", "tier": "P2", "strategy": "Part of the portable four-event coverage." }, { "id": "hooks.block", "area": "hooks", "label": "Hook can block a tool call", "tier": "P2", "strategy": "Adapter refuses to install a guard where the host can't block; every guard also has a gate." }, { "id": "hooks.inject-context", "area": "hooks", "label": "Hook can inject context", "tier": "P2", "strategy": "Declare canInjectContext per adapter." }, { "id": "hooks.rewrite-input", "area": "hooks", "label": "Hook can rewrite tool input", "tier": "P3", "strategy": "Declare canRewriteInput per adapter; don't depend on it." }, { "id": "hooks.rewrite-output", "area": "hooks", "label": "Hook can rewrite tool output", "tier": "P3", "strategy": "Declare canRewriteOutput per adapter; don't depend on it." }, { "id": "hooks.model-level", "area": "hooks", "label": "Model-level hooks (before/after model call)", "tier": "P3", "strategy": "Host-exclusive; no portable equivalent." }, { "id": "hooks.inferential", "area": "hooks", "label": "Inferential hook handlers (prompt/agent)", "tier": "P3", "strategy": "Host-exclusive; use a command handler for portability." }, { "id": "hooks.fail-closed", "area": "hooks", "label": "Hooks can be configured or default to fail closed", "tier": "P2", "strategy": "Declare open/closed per hook; the wrapper enforces it; every guard has a gate." }, { "id": "hooks.cross-read", "area": "hooks", "label": "Reads Claude Code hook configuration", "tier": "P2", "strategy": "Don't rely on cross-reads for guards; generate native config." }, { "id": "policy.rules", "area": "policy", "label": "Allow / ask / deny permission rules", "tier": "P2", "strategy": "Neutral policy.yaml fed to generators; enforcement lives in the sandbox and gates." }, { "id": "policy.repo", "area": "policy", "label": "Permissions can be committed in the repo", "tier": "P2", "strategy": "Where they can't, document the user-level setup and rely on gates." }, { "id": "policy.sandbox", "area": "policy", "label": "OS-level sandbox", "tier": "P2", "strategy": "Containers or devcontainers for real, portable isolation." }, { "id": "policy.ignore", "area": "policy", "label": "Ignore list that actually holds", "tier": "P3", "strategy": "Treat ignore files as advisory everywhere; real enforcement is sandbox or managed policy." }, { "id": "policy.managed", "area": "policy", "label": "Org / enterprise managed policy", "tier": "P3", "strategy": "Per host; tell users what is enforcement and what is advisory." }, { "id": "mcp.client", "area": "mcp", "label": "MCP client", "tier": "P1", "strategy": "Wrap capabilities as MCP servers; every host gets the same tool." }, { "id": "mcp.project-config", "area": "mcp", "label": "Project-level MCP config file (path in note)", "tier": "P2", "strategy": "Neutral servers.yaml generated per host; pinned stdio subset; env-var names only." }, { "id": "mcp.remote", "area": "mcp", "label": "Remote (HTTP) MCP servers", "tier": "P2", "strategy": "Wire remote servers and secrets per host." }, { "id": "intel.lsp", "area": "intel", "label": "Language-server tool exposed to the model", "tier": "P3", "strategy": "Wrap code intelligence as an MCP server instead." }, { "id": "intel.memory", "area": "intel", "label": "Automatic memory across sessions", "tier": "P3", "strategy": "Tool-local; durable facts belong in AGENTS.md." }, { "id": "plugins.package", "area": "plugins", "label": "Plugin / extension packages", "tier": "P2", "strategy": "Generate two manifests: Agent Plugins and Claude's." }, { "id": "plugins.marketplace", "area": "plugins", "label": "Marketplace / catalog", "tier": "P2", "strategy": "Git-hosted catalogs; test install per host because parts are dropped silently." }, { "id": "plugins.agent-plugins", "area": "plugins", "label": "Agent Plugins 1.0 client", "tier": "P1", "strategy": "Only skills and MCP travel in the standard's scope." }, { "id": "plugins.claude-manifest", "area": "plugins", "label": "Reads Claude plugin manifest (.claude-plugin/)", "tier": "P2", "strategy": "A Claude manifest reaches several hosts; still test each." } ], "hosts": [ { "id": "claude-code", "label": "Claude Code", "reviewed": "2026-10-18", "headless": "claude -p", "homeDirs": [ ".claude/", "~/.claude/", "~/.claude.json" ], "summary": "Has the most hooks of any tool (33 events, 5 handler types), plus path-scoped rules and skills that can fork into subagents. Other tools often read its formats. It reads AGENTS.md only in some cases and ignores .agents/skills.", "unique": [ { "title": "33 hook events, 5 handler types", "detail": "Handlers can be command, http, mcp_tool, prompt or (experimental) agent. updatedToolOutput works for any tool, PreToolUse can defer, and PermissionRequest hooks can supply updatedInput.", "source": "tools/claude-code.md §7, §14" }, { "title": "Skills that fork and carry hooks", "detail": "Skills can run in a subagent (context: fork), pre-approve tools, ship their own hooks, inject live shell output with ! blocks, and scope by paths.", "source": "tools/claude-code.md §4, §14" }, { "title": "Auto permission mode", "detail": "In auto mode a classifier reviews actions. There is also dontAsk, and a sandbox that protects credentials. Anthropic reports 93% of prompts approved.", "source": "tools/claude-code.md §8; topics/evidence-what-works.md (Anthropic auto-mode post, 2026-03-25)" }, { "title": "Subagent isolation and memory", "detail": "Worktree isolation, per-agent persistent memory, per-agent hooks and MCP scoping, depth 3 / concurrency 20 limits, --agent main-session mode.", "source": "tools/claude-code.md §6" }, { "title": "Plugins with dependencies and monitors", "detail": "userConfig with secure storage, dependencies, monitors, LSP servers, bin on PATH, seven plugin source types, org policy over marketplaces.", "source": "tools/claude-code.md §12" }, { "title": "Cloud, teleport and scheduling", "detail": "Cloud sessions, --teleport, Remote Control, Channels, Routines, /loop, auto-fix PRs, agent teams.", "source": "tools/claude-code.md §1, §14" }, { "title": "Claude as MCP server and SDK", "detail": "claude mcp serve exposes Claude Code as an MCP server. The Agent SDK (Python, TypeScript) runs the same engine and loads .claude/ config.", "source": "tools/claude-code.md §2, §10" } ], "gotchas": [ "AGENTS.md is skipped if any CLAUDE.md or CLAUDE.local.md exists on the path, even a tiny one. Use a CLAUDE.md that contains @AGENTS.md.", "Does not read .agents/skills. Put skills in .claude/skills as a link or copy.", "Hooks fail open by default: a mistyped path or exit 1 won't block. Only exit 2 (blocking events), valid deny JSON or onFailure: \"block\" (command/http, v2.1.295+) blocks.", "claude -p and cloud sessions run repo hooks and .mcp.json servers with no trust prompt unless --bare.", "Glob and Grep are off by default, so a Grep|Glob hook matcher never fires. Searches arrive as Bash calls.", "Cloud sessions ignore ~/.claude and user-only plugins. Commit skills and settings to the repo.", "The managed-only Project instructions setting drops project CLAUDE.md, breaking the @AGENTS.md wrapper." ], "cells": { "surface.cli": { "level": "N", "native": "claude", "note": "Interactive terminal CLI; all interfaces share one engine, so CLAUDE.md, settings and MCP work across them.", "source": "tools/claude-code.md §1-2" }, "surface.ide": { "level": "N", "native": "VS Code, JetBrains, desktop app", "note": "Extensions for VS Code and JetBrains plus a desktop app; same engine and config as the CLI.", "source": "tools/claude-code.md §1; https://code.claude.com/docs/en/overview" }, "surface.cloud": { "level": "N", "native": "claude.ai/code, claude --cloud, --teleport", "note": "Managed VMs read repo .claude/ (settings, agents, skills, hooks) but NOT ~/.claude or user-only plugins; LSP servers do not start.", "source": "tools/claude-code.md §2" }, "headless.run": { "level": "N", "native": "claude -p", "note": "Same engine as the Agent SDK; --bare skips auto-discovery and is recommended for CI. Without --bare it runs project hooks and .mcp.json without trust prompts.", "source": "tools/claude-code.md §2" }, "headless.json": { "level": "N", "native": "--output-format json | stream-json; --json-schema", "note": "json gives result, session_id, cost; stream-json is NDJSON; system/init event lists plugins, MCP servers and capabilities.", "source": "tools/claude-code.md §2" }, "instr.agents-md": { "level": "P", "native": "AGENTS.md (v2.1.277+, only if no CLAUDE.md)", "note": "Read only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists on the path; else needs @AGENTS.md. Never reads AGENTS.override.md or .agents/.", "source": "tools/claude-code.md §3; cross-platform-ai-harness.md §4 note 1" }, "instr.claude-md": { "level": "N", "native": "CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md", "note": "Managed, user, project and local tiers; delivered as a user message, context not enforcement.", "source": "tools/claude-code.md §3" }, "instr.own-file": { "level": "N", "native": "CLAUDE.md", "note": "Its own always-on file; recommended bridge is CLAUDE.md containing @AGENTS.md plus Claude-only notes.", "source": "tools/claude-code.md §3" }, "instr.nested": { "level": "N", "native": "subdirectory CLAUDE.md (lazy)", "note": "Ancestors load at launch; subdirectory files load on demand when Claude reads files there. Nested AGENTS.md only if the dir has no CLAUDE.md.", "source": "tools/claude-code.md §3" }, "instr.imports": { "level": "N", "native": "@path imports", "note": "Recursive to 4 hops; skipped in code blocks; imports outside cwd need one-time approval; loaded at launch, so no context saving.", "source": "tools/claude-code.md §3" }, "rules.glob": { "level": "N", "native": ".claude/rules/*.md (paths)", "note": "Only frontmatter field is paths; rules without paths load at launch. Path-scoped rules trigger when Claude reads or edits a matching file (Read, Write, Edit, or a single-file Bash read).", "source": "tools/claude-code.md §3" }, "rules.description": { "level": "-", "native": "", "note": "No description-activated rules; use a skill (description-based) instead.", "source": "cross-platform-ai-harness.md §4 matrix; tools/claude-code.md §3" }, "skills.agents-dir": { "level": "-", "native": "", "note": "Claude Code does not read .agents/skills (re-checked raw 2026-09-29); the only core host that does not.", "source": "tools/claude-code.md §4, §15" }, "skills.claude-dir": { "level": "N", "native": ".claude/skills//SKILL.md", "note": "Enterprise > personal > project precedence; nested .claude/skills auto-discovered; plugin skills namespaced /plugin:skill.", "source": "tools/claude-code.md §4" }, "skills.spec": { "level": "N", "native": "SKILL.md (agentskills.io compatible)", "note": "All fields optional, only description recommended; license, compatibility, metadata accepted; listing budget 1% of context, 1,536 chars per skill.", "source": "tools/claude-code.md §4" }, "skills.extras": { "level": "N", "native": "context: fork, paths, allowed-tools, hooks, when_to_use, effort...", "note": "Many extras beyond the six spec fields; unknown fields ignored without a warning.", "source": "tools/claude-code.md §4" }, "commands.format": { "level": "P", "native": ".claude/commands/.md", "note": "Still works but merged into skills (a file and a skill dir both create /name); prefer skills for new work.", "source": "tools/claude-code.md §5" }, "agents.profiles": { "level": "N", "native": ".claude/agents/*.md", "note": "Markdown plus YAML; only name and description required; subagents with worktree isolation, memory, hooks and MCP scoping.", "source": "tools/claude-code.md §6" }, "agents.tool-limits": { "level": "N", "native": "tools / disallowedTools (Agent(x) limits spawns)", "note": "Allowlist and denylist per agent; plugin agents may not use hooks, mcpServers or permissionMode.", "source": "tools/claude-code.md §6" }, "agents.cross-read": { "level": "-", "native": "", "note": "Does not read other hosts' agent folders; /import (v2.1.213+) copies another agent's config once.", "source": "tools/claude-code.md §3, §6" }, "hooks.shell": { "level": "N", "native": "hooks in settings.json (33 events)", "note": "33 events, five handler types: command, http, mcp_tool, prompt, agent (experimental).", "source": "tools/claude-code.md §7" }, "hooks.session-start": { "level": "N", "native": "SessionStart", "note": "Plain stdout or additionalContext becomes context; SessionEnd, Setup also exist.", "source": "tools/claude-code.md §7" }, "hooks.tool-before": { "level": "N", "native": "PreToolUse", "note": "permissionDecision allow|deny|ask|defer, updatedInput, additionalContext; exit 2 blocks before rules run.", "source": "tools/claude-code.md §7" }, "hooks.tool-after": { "level": "N", "native": "PostToolUse (+ PostToolUseFailure, PostToolBatch)", "note": "Can replace tool output; exit 2 is not honoured here since the tool already ran.", "source": "tools/claude-code.md §7" }, "hooks.agent-stop": { "level": "N", "native": "Stop (+ SubagentStop)", "note": "decision block keeps the agent going; exit 2 blocks.", "source": "tools/claude-code.md §7" }, "hooks.block": { "level": "N", "native": "exit 2 or permissionDecision deny", "note": "Exit 2 blocks only on events marked Yes; a deny/ask permission rule still wins over a hook allow.", "source": "tools/claude-code.md §7" }, "hooks.inject-context": { "level": "N", "native": "additionalContext", "note": "Capped at 10,000 chars (overflow spills to a file); available on SessionStart, PreToolUse, Stop, SubagentStart and more.", "source": "tools/claude-code.md §7" }, "hooks.rewrite-input": { "level": "N", "native": "PreToolUse updatedInput", "note": "Also PermissionRequest decision.updatedInput.", "source": "tools/claude-code.md §7" }, "hooks.rewrite-output": { "level": "N", "native": "PostToolUse updatedToolOutput", "note": "All tools since v2.1.121; changes only what Claude sees. updatedMCPToolOutput is the older MCP-only field.", "source": "tools/claude-code.md §7; open-questions.md (resolved)" }, "hooks.model-level": { "level": "-", "native": "", "note": "No before/after model-call hooks; nearest are PreModelSwitch/PostModelSwitch (model switch only) and UserPromptSubmit.", "source": "cross-platform-ai-harness.md §6; tools/claude-code.md §7" }, "hooks.inferential": { "level": "N", "native": "type: prompt | agent", "note": "Prompt hooks return ok/reason; agent hooks are experimental and unsupported on PermissionRequest.", "source": "tools/claude-code.md §7" }, "hooks.fail-closed": { "level": "N", "native": "onFailure: \"block\" (command and http hooks, v2.1.295+)", "note": "Per-hook opt-in: a hook that cannot start, times out, exits other than 0/2 or prints invalid JSON then blocks; default is \"continue\" (fail open). No effect on Stop, SubagentStop, TaskCompleted, TeammateIdle or async hooks.", "source": "tools/claude-code.md §7, §15; https://code.claude.com/docs/en/hooks#block-the-action-when-a-hook-fails" }, "hooks.cross-read": { "level": "-", "native": "", "note": "Claude is the source format that Cursor, Copilot CLI and (opt-in) VS Code read; it reads no other host's hooks.", "source": "cross-platform-ai-harness.md §5" }, "policy.rules": { "level": "N", "native": "permissions allow/ask/deny in settings.json", "note": "Order deny, ask, allow; first match wins; specificity does not matter. Modes include plan, auto (classifier), dontAsk.", "source": "tools/claude-code.md §8" }, "policy.repo": { "level": "N", "native": ".claude/settings.json", "note": "Committed project rules; allow rules and hooks follow workspace trust; .claude/settings.local.json for personal overrides.", "source": "tools/claude-code.md §8" }, "policy.sandbox": { "level": "N", "native": "/sandbox (Seatbelt, bubblewrap)", "note": "macOS Seatbelt, Linux/WSL2 bubblewrap; covers Bash and children; failIfUnavailable defaults to warn and run unsandboxed.", "source": "tools/claude-code.md §8" }, "policy.ignore": { "level": "P", "native": "permissions.deny Read(...), sandbox.filesystem.denyRead", "note": "No ignore file. Read deny covers cat/head/tail/sed/tee and redirects but not grep -r; OS-level needs sandbox denyRead.", "source": "tools/claude-code.md §9" }, "policy.managed": { "level": "N", "native": "managed-settings.json, MDM, server-managed", "note": "Highest precedence; managed CLAUDE.md cannot be excluded; managed hooks cannot be disabled from lower levels.", "source": "tools/claude-code.md §8" }, "mcp.client": { "level": "N", "native": "claude mcp add|list|...", "note": "stdio, http (recommended), sse (deprecated), ws; scopes local, project, user.", "source": "tools/claude-code.md §10" }, "mcp.project-config": { "level": "N", "native": ".mcp.json", "note": "Root-level {mcpServers}; project servers need approval interactively, but -p and cloud load them without prompting. Duplicate-name precedence: managedMcpServers > local > project > user > plugin > claude.ai connectors.", "source": "tools/claude-code.md §10" }, "mcp.remote": { "level": "N", "native": "type: http, url, headers, headersHelper, oauth", "note": "${VAR} and ${VAR:-default} expansion; credential vars read as empty in remote url/headers.", "source": "tools/claude-code.md §10" }, "intel.lsp": { "level": "N", "native": "LSP tool via plugins (.lsp.json)", "note": "Plugin-only: no repo-level LSP config outside a plugin; not started in cloud sessions. Also diagnostics after each edit.", "source": "tools/claude-code.md §11" }, "intel.memory": { "level": "N", "native": "auto memory: ~/.claude/projects//memory/MEMORY.md", "note": "On by default; first 200 lines/25 KB loaded; machine-local; subagents do not inherit it (forks do).", "source": "tools/claude-code.md §13" }, "plugins.package": { "level": "N", "native": ".claude-plugin/plugin.json", "note": "Bundles skills, commands, agents, hooks, MCP, LSP, monitors, bin; only name required; userConfig and dependencies supported.", "source": "tools/claude-code.md §12" }, "plugins.marketplace": { "level": "N", "native": ".claude-plugin/marketplace.json", "note": "Seven plugin source types; add from GitHub, git URL, local path or hosted JSON; strictKnownMarketplaces allowlist for orgs.", "source": "tools/claude-code.md §12" }, "plugins.agent-plugins": { "level": "-", "native": "", "note": "Not listed as an Agent Plugins 1.0 compatible client; whether it will load them natively is an open question.", "source": "sources/agent-plugins-spec.md; open-questions.md" }, "plugins.claude-manifest": { "level": "N", "native": ".claude-plugin/plugin.json", "note": "The source format. Also read by VS Code Copilot, Copilot CLI and Codex; Codex path confirmed in source.", "source": "tools/claude-code.md §12; verification log row 31" } } }, { "id": "codex", "label": "OpenAI Codex", "reviewed": "2026-10-18", "headless": "codex exec", "homeDirs": [ ".codex/", "~/.codex/", ".agents/", "~/.agents/", "AGENTS.md", "/etc/codex/" ], "summary": "Codex is built around the sandbox. Sandbox mode and approval policy are separate, and execpolicy rules are testable. Hooks work much like Claude's but need a trust review. Agent profiles are TOML, with Claude plugin manifests as a fallback.", "unique": [ { "title": "Sandbox x approval axes", "detail": "Sandbox mode and approval policy are set independently, with granular approvals and an auto_review (Guardian) reviewer. Permission profiles support extends and network domain rules.", "source": "tools/codex.md §8" }, { "title": "execpolicy Starlark rules", "detail": "prefix_rule() with match/not_match self-tests, checked with 'codex execpolicy check'. The most restrictive rule wins. These rules are command policy, not instructions.", "source": "tools/codex.md §8; cross-platform-ai-harness.md §6" }, { "title": "Hash-keyed hook trust", "detail": "Hooks that are not managed must be approved in /hooks, and the approval is tied to a hash of the hook definition. Untrusted projects skip project .codex layers. Managed hooks skip review.", "source": "tools/codex.md §7; cross-platform-ai-harness.md §6" }, { "title": "AGENTS.override.md", "detail": "Per-directory local override plus configurable fallback filenames, under a 32 KiB combined cap.", "source": "tools/codex.md §3; cross-platform-ai-harness.md §6" }, { "title": "mcp_tool and async hooks", "detail": "Hook handler type mcp_tool, async command hooks (max 8), Interrupt event, and spill files for oversized hook context.", "source": "tools/codex.md §7" }, { "title": "Rich per-agent TOML", "detail": "Agent TOML can set sandbox_mode, model_reasoning_effort (up to ultra), MCP servers and skill config.", "source": "tools/codex.md §6" }, { "title": "GitHub Action and SDKs", "detail": "openai/codex-action with safety-strategy, TypeScript and Python SDKs (Python drives the app-server). codex mcp-server was removed.", "source": "tools/codex.md §2, §10" }, { "title": "Reads Claude and Cursor marketplaces", "detail": "Marketplace lookup includes .claude-plugin/ and .cursor-plugin/ files, and sets CLAUDE_PLUGIN_ROOT for plugin hooks.", "source": "tools/codex.md §12" } ], "gotchas": [ "In Codex, .codex/rules/*.rules is command policy (prefix_rule), not instructions. Do not generate instruction rules there.", "Hook matchers have no Read or Grep tools, so file reads show up as Bash. Hosted web_search fires no hooks.", "Unsupported hook outputs (ask, updatedMCPToolOutput, empty-reason deny) fail open and the tool call proceeds.", "Hook prompt and agent handlers are skipped silently, so Claude hook files load and do nothing.", "Hooks and project .codex config need trust review (/hooks); CI needs managed hooks or --dangerously-bypass-hook-trust.", "AGENTS.md stops loading files at 32 KiB combined (project_doc_max_bytes), with no imports or globs. The docs have moved to learn.chatgpt.com/docs." ], "cells": { "surface.cli": { "level": "N", "native": "codex (TUI)", "note": "Codex CLI; shares ~/.codex/config.toml with IDE extension and ChatGPT desktop app.", "source": "tools/codex.md §1" }, "surface.ide": { "level": "N", "native": "IDE extension; desktop app", "note": "IDE extension and desktop app (macOS, Windows, Linux) share the CLI config.", "source": "tools/codex.md §1" }, "surface.cloud": { "level": "N", "native": "Codex Cloud (web, mobile, desktop; `codex cloud` CLI)", "note": "Current Cloud uses reusable published environments and isolated task workspaces; saved VM state is recoverable for up to 7 days. The setup-script workflow and 12 h cache describe Codex Cloud (Legacy). Plugin loading in current Cloud is unverified.", "source": "tools/codex.md §2" }, "headless.run": { "level": "N", "native": "codex exec", "note": "stdout carries only final message; read-only sandbox by default; CODEX_API_KEY for CI (scope it to Codex, not job-level for repo-controlled code); errors if a required MCP server fails.", "source": "tools/codex.md §2" }, "headless.json": { "level": "N", "native": "codex exec --json; --output-schema", "note": "JSONL events include thread.started, turn.started/completed/failed, item.*, and error; --output-last-message and --output-schema (JSON Schema) are also available.", "source": "tools/codex.md §2" }, "instr.agents-md": { "level": "N", "native": "AGENTS.md; AGENTS.override.md", "note": "Global then Git root down to cwd; one file per directory; 32 KiB combined cap (project_doc_max_bytes; sources disagree whether combined or per file), then stops adding files.", "source": "tools/codex.md §3" }, "instr.claude-md": { "level": "C", "native": "project_doc_fallback_filenames", "note": "Not read by default; add CLAUDE.md via the fallback-filenames config key.", "source": "cross-platform-ai-harness.md §4 note 2; tools/codex.md §3" }, "instr.own-file": { "level": "P", "native": "AGENTS.override.md", "note": "No Codex-specific instruction file; AGENTS.md is the shared one. AGENTS.override.md is a per-directory local override (also ~/.codex).", "source": "tools/codex.md §3, §14" }, "instr.nested": { "level": "N", "native": "nested AGENTS.md (root to cwd)", "note": "Walks Git root down to cwd; closer files appear later and override. project_root_markers configurable (default .git, .hg, .sl).", "source": "tools/codex.md §3" }, "instr.imports": { "level": "-", "native": "", "note": "No import syntax documented; no @ inlining.", "source": "tools/codex.md §3" }, "rules.glob": { "level": "-", "native": "", "note": "No glob-scoped instruction rules; scope via nested AGENTS.md. .codex/rules/ is command policy, not instructions.", "source": "tools/codex.md §3, §15" }, "rules.description": { "level": "-", "native": "", "note": "No description-activated rules; use a skill instead.", "source": "tools/codex.md §3" }, "skills.agents-dir": { "level": "N", "native": ".agents/skills; ~/.agents/skills", "note": "Scans every directory from cwd up to repo root; also /etc/codex/skills (admin) and bundled system skills; symlinks followed.", "source": "tools/codex.md §4" }, "skills.claude-dir": { "level": "-", "native": "", "note": "Not read; deliver skills via .agents/skills.", "source": "cross-platform-ai-harness.md §4 matrix; tools/codex.md §4" }, "skills.spec": { "level": "N", "native": "SKILL.md (name, description)", "note": "Agent Skills open standard; listing budget 2% of context or 8,000 chars; body loads on use; $skill-name explicit invocation.", "source": "tools/codex.md §4" }, "skills.extras": { "level": "P", "native": "agents/openai.yaml sidecar", "note": "Extras live in a sidecar, not frontmatter: interface, policy.allow_implicit_invocation, MCP dependencies. Frontmatter extras undocumented.", "source": "tools/codex.md §4" }, "commands.format": { "level": "P", "native": "~/.codex/prompts/*.md (/prompts:name)", "note": "Custom prompts deprecated in favour of skills; user-level only, no repo-level commands directory.", "source": "tools/codex.md §5" }, "agents.profiles": { "level": "N", "native": ".codex/agents/*.toml", "note": "One TOML per agent; required name, description, developer_instructions. Built-ins: default, worker, explorer.", "source": "tools/codex.md §6" }, "agents.tool-limits": { "level": "P", "native": "sandbox_mode, mcp_servers, skills.config", "note": "No tool allowlist; restriction is by sandbox mode and MCP/skill config per agent. No lossless mapping from a tool list.", "source": "topics/agents-and-commands.md; tools/codex.md §6" }, "agents.cross-read": { "level": "-", "native": "", "note": "No reads of other hosts' agent folders documented.", "source": "topics/agents-and-commands.md (cross-tool reads); Cursor reads .codex/agents" }, "hooks.shell": { "level": "N", "native": ".codex/hooks.json or [hooks] in config.toml", "note": "12 events; handlers command and mcp_tool (prompt/agent parsed but skipped). On by default; non-managed hooks need /hooks trust review.", "source": "tools/codex.md §7" }, "hooks.session-start": { "level": "N", "native": "SessionStart", "note": "Matcher on source: startup|resume|clear|compact|fork.", "source": "tools/codex.md §7" }, "hooks.tool-before": { "level": "N", "native": "PreToolUse", "note": "Matchers see Bash, apply_patch (also Edit/Write), MCP tools; no Read/Grep tools; hosted web_search fires no hooks.", "source": "tools/codex.md §7" }, "hooks.tool-after": { "level": "N", "native": "PostToolUse", "note": "Same tool coverage as PreToolUse; decision block replaces output with feedback but cannot undo side effects.", "source": "tools/codex.md §7" }, "hooks.agent-stop": { "level": "N", "native": "Stop (and SubagentStop)", "note": "decision: block with reason continues the turn.", "source": "tools/codex.md §7" }, "hooks.block": { "level": "N", "native": "permissionDecision: deny; exit 2", "note": "Deny needs non-empty reason; empty-reason deny or empty-stderr exit 2 fails open. ask and continue:false also fail open.", "source": "tools/codex.md §7" }, "hooks.inject-context": { "level": "N", "native": "hookSpecificOutput.additionalContext", "note": "Accepted on exactly five events: SessionStart, SubagentStart, UserPromptSubmit, PreToolUse, PostToolUse. Capped near 2,500 tokens by default.", "source": "tools/codex.md §7; open-questions.md (resolved 2026-09-29)" }, "hooks.rewrite-input": { "level": "N", "native": "PreToolUse updatedInput", "note": "Only together with permissionDecision allow (since rust-v0.131.0); Bash and apply_patch need a string command. Bare allow unsupported.", "source": "tools/codex.md §7; open-questions.md (resolved 2026-09-29)" }, "hooks.rewrite-output": { "level": "-", "native": "", "note": "updatedMCPToolOutput and suppressOutput are parsed but unsupported (hook marked failed). PostToolUse block only replaces output with feedback.", "source": "tools/codex.md §7" }, "hooks.model-level": { "level": "-", "native": "", "note": "No before/after model-call events.", "source": "tools/codex.md §7 (event list)" }, "hooks.inferential": { "level": "-", "native": "", "note": "prompt and agent handlers are parsed but skipped, so Claude hook files using them load and silently do nothing.", "source": "tools/codex.md §7, §15" }, "hooks.fail-closed": { "level": "-", "native": "", "note": "No per-hook fail-closed option. Deny works via exit 2 or JSON; unsupported or invalid outputs fail open and the tool call proceeds.", "source": "tools/codex.md §7, §15" }, "hooks.cross-read": { "level": "P", "native": "plugin hooks/hooks.json (Claude plugins)", "note": "Does not read .claude/settings.json. Claude-format hook files in plugins load; CLAUDE_PLUGIN_ROOT/DATA env set for compatibility. Untested end to end.", "source": "tools/codex.md §7; topics/plugins-and-distribution.md" }, "policy.rules": { "level": "N", "native": ".rules prefix_rule(); approval_policy; permission profiles", "note": "Sandbox mode and approval policy are separate axes; execpolicy allow|prompt|forbidden with self-tests. .rules is command policy only.", "source": "tools/codex.md §8" }, "policy.repo": { "level": "P", "native": ".codex/config.toml; .codex/rules/", "note": "Repo layers load only in trusted projects; untrusted projects skip project .codex config, hooks and rules.", "source": "tools/codex.md §8, §14" }, "policy.sandbox": { "level": "N", "native": "sandbox_mode (Seatbelt / bubblewrap / Windows)", "note": "read-only, workspace-write, danger-full-access; .git, .agents, .codex read-only inside writable roots; network off by default.", "source": "tools/codex.md §8" }, "policy.ignore": { "level": "P", "native": "permission-profile filesystem deny globs; permissions.filesystem.deny_read", "note": "No .codexignore. Repo-level don't-read is permission-profile filesystem deny rules (glob subpaths set to \"deny\", e.g. \"**/*.env\" under :workspace_roots) plus sandbox; admins can enforce permissions.filesystem.deny_read.", "source": "cross-platform-ai-harness.md §4 matrix; tools/codex.md §9" }, "policy.managed": { "level": "N", "native": "requirements.toml; MDM; cloud bundle", "note": "Separate enforced stack from config stack; managed hooks skip trust review; legacy managed_config.toml sits above CLI flags.", "source": "tools/codex.md §8" }, "mcp.client": { "level": "N", "native": "[mcp_servers.]; codex mcp add", "note": "stdio and HTTP; codex mcp-server was removed (use the app server). No ${VAR} interpolation; secrets passed by env-var name.", "source": "tools/codex.md §10" }, "mcp.project-config": { "level": "N", "native": ".codex/config.toml", "note": "TOML [mcp_servers]; loaded for trusted projects only. Also ~/.codex/config.toml.", "source": "tools/codex.md §10" }, "mcp.remote": { "level": "N", "native": "url + auth / bearer_token_env_var", "note": "HTTP servers with oauth or chatgpt auth, headers, env_http_headers, http_headers_helper.", "source": "tools/codex.md §10" }, "intel.lsp": { "level": "-", "native": "", "note": "No LSP integration or tool documented. Wrap code intelligence as an MCP server.", "source": "tools/codex.md §11" }, "intel.memory": { "level": "P", "native": "[features] memories; ~/.codex/memories/", "note": "Off by default; opt in via config or Settings; generated async, secrets redacted; /memories per chat. Supplements, not replaces, AGENTS.md.", "source": "tools/codex.md §13" }, "plugins.package": { "level": "N", "native": ".codex-plugin/plugin.json; root plugin.json", "note": "Bundles skills, MCP, hooks, browser extensions, .app.json. Installed via /plugins or codex plugin marketplace.", "source": "tools/codex.md §12" }, "plugins.marketplace": { "level": "N", "native": ".agents/plugins/marketplace.json", "note": "Also reads .claude-plugin/ and .cursor-plugin/ marketplace files; bare-string local sources accepted; git-subdir and npm sources.", "source": "tools/codex.md §12" }, "plugins.agent-plugins": { "level": "N", "native": "root plugin.json with agent-plugins.org $schema", "note": "Listed compatible client. Docs: scaffold still writes .codex-plugin layout, not the portable one; OpenAI settings under extensions.com.openai.", "source": "sources/agent-plugins-spec.md; tools/codex.md §12" }, "plugins.claude-manifest": { "level": "C", "native": ".claude-plugin/plugin.json (fallback)", "note": "Fallback after root plugin.json and .codex-plugin; path confirmed only in source (manifest.rs); docs say only Claude-compatible manifests accepted.", "source": "tools/codex.md §12; open-questions.md (resolved 2026-09-29)" } } }, { "id": "github-copilot", "label": "GitHub Copilot", "reviewed": "2026-10-18", "headless": "copilot -p", "homeDirs": [ "~/.copilot/", "~/.agents/", "~/.claude/ (VS Code reads; CLI reads some)" ], "summary": "Copilot is several products that share some files: VS Code Local and Agent Host, the CLI, the cloud agent and code review. It reads more formats than other tools (AGENTS.md, CLAUDE.md, GEMINI.md, .claude), and governance sits in GitHub org settings.", "unique": [ { "title": "excludeAgent on path instructions", "detail": "Scope an *.instructions.md file to code-review or cloud-agent only, so a rule can target which Copilot agent reads it.", "source": "tools/github-copilot.md §3, §14" }, { "title": "Custom-agent handoffs (VS Code)", "detail": "Agent frontmatter lists handoffs (label, agent, prompt, send, model) for guided transitions between agents. Not supported on Cloud.", "source": "tools/github-copilot.md §6" }, { "title": "MCP inputs prompting (VS Code)", "detail": "An inputs array with ${input:id} asks for secrets at runtime instead of storing them. Also supports envFile and a sandbox per server.", "source": "tools/github-copilot.md §10" }, { "title": "Policy hooks users cannot disable", "detail": "CLI hooks under /etc/github-copilot/policy.d always apply. disableAllHooks in repo settings skips every hook except these.", "source": "tools/github-copilot.md §7" }, { "title": "HTTP and prompt hook handlers plus extra events", "detail": "http handlers (HTTPS required for preToolUse), userPromptTransformed, permissionRequest, errorOccurred events.", "source": "tools/github-copilot.md §7, §14" }, { "title": "Cloud agent with setup steps and firewall", "detail": "Turns an issue into a PR in a short-lived Actions environment, set up with copilot-setup-steps.yml and behind a built-in firewall. /delegate hands work over from the CLI. Orgs can add custom agents and instructions.", "source": "tools/github-copilot.md §14" }, { "title": "CLI autopilot, fleet, /after, first-class LSP", "detail": "Autopilot mode, --fleet, /after scheduled prompts, --ui-server (unverified), and lsp.json LSP config with copilot lsp list.", "source": "tools/github-copilot.md §14" }, { "title": "Hosted Copilot Memory", "detail": "GitHub-hosted repo and user memory shared across cloud agent, review and CLI, with citations validated against the branch.", "source": "tools/github-copilot.md §13" } ], "gotchas": [ "Hook counts depend on the interface: 14 for CLI and cloud agent, 8 for VS Code Local, where notification, errorOccurred and userPromptTransformed never fire.", "Timeouts fail open for every event, including preToolUse, even though preToolUse errors deny.", "VS Code Local ignores hook matcher values, so every command for the event runs.", "The CLI does not read .vscode/mcp.json. Use .mcp.json or .github/mcp.json (root key mcpServers).", "VS Code skill names with invalid characters silently fail to load. The name must match the directory.", "The cloud agent loads only committed repo files. It cannot see symlinks, user scope or plugins." ], "cells": { "surface.cli": { "level": "N", "native": "copilot (TUI)", "note": "Copilot CLI: interactive TUI plus headless; autopilot and fleet modes.", "source": "tools/github-copilot.md §2" }, "surface.ide": { "level": "N", "native": "VS Code agent mode (Local / Agent Host); JetBrains", "note": "VS Code Local agent is slated for removal; Agent Host is the successor. Skills also in JetBrains agent mode.", "source": "tools/github-copilot.md §2, §1" }, "surface.cloud": { "level": "N", "native": "Cloud coding agent (GitHub Actions)", "note": "Ephemeral env, 59-min cap, one repo and one PR per task. Reads only committed repo files, no user scope or plugins.", "source": "tools/github-copilot.md §2, §14" }, "headless.run": { "level": "N", "native": "copilot -p \"...\"", "note": "CLI only. CI auth via COPILOT_GITHUB_TOKEN / GH_TOKEN; fine-grained PAT with Copilot Requests permission.", "source": "tools/github-copilot.md §2" }, "headless.json": { "level": "N", "native": "--output-format json", "note": "CLI streams JSONL. Default is text.", "source": "tools/github-copilot.md §2" }, "instr.agents-md": { "level": "N", "native": "AGENTS.md", "note": "Read by Cloud, CLI, VS Code and Review. Nearest wins on GitHub docs; CLI combines and dedupes with no defined precedence.", "source": "tools/github-copilot.md §3" }, "instr.claude-md": { "level": "C", "native": "CLAUDE.md (root, .claude/CLAUDE.md); GEMINI.md", "note": "CLI reads CLAUDE.md and GEMINI.md; GitHub docs treat CLAUDE.md as an AGENTS.md alternative; VS Code Local via chat.useClaudeMdFile; Review also reads them.", "source": "tools/github-copilot.md §3" }, "instr.own-file": { "level": "N", "native": ".github/copilot-instructions.md", "note": "All interfaces. Also .github/instructions/**/*.instructions.md, ~/.copilot/copilot-instructions.md, org and personal instructions on GitHub.", "source": "tools/github-copilot.md §3" }, "instr.nested": { "level": "P", "native": "AGENTS.md nearest-wins; chat.useNestedAgentsMdFiles", "note": "VS Code nested AGENTS.md is off by default (Local agent only; the \"experimental\" wording is gone from the current page). Cloud: nearest wins. CLI: standard locations, combined.", "source": "tools/github-copilot.md §3" }, "instr.imports": { "level": "P", "native": "@ file references", "note": "CLI supports @ refs in copilot-instructions.md, AGENTS.md, CLAUDE.md; not expanded in GEMINI.md. Other interfaces not documented in KB.", "source": "tools/github-copilot.md §3" }, "rules.glob": { "level": "N", "native": "*.instructions.md with applyTo", "note": "Comma-separated globs; excludeAgent code-review|cloud-agent. VS Code also reads .claude/rules with paths:; CLI reads .claude/rules since 1.0.89 (paths or applyTo).", "source": "tools/github-copilot.md §3" }, "rules.description": { "level": "P", "native": "VS Code instructions file description match", "note": "VS Code only: agent may load an instructions file on demand when its description matches. Not documented for CLI or Cloud.", "source": "tools/github-copilot.md §3" }, "skills.agents-dir": { "level": "N", "native": ".agents/skills, ~/.agents/skills", "note": "Also .github/skills and ~/.copilot/skills. Read by Cloud, Review, CLI, VS Code, JetBrains.", "source": "tools/github-copilot.md §4" }, "skills.claude-dir": { "level": "C", "native": ".claude/skills", "note": "Project dir; VS Code also ~/.claude/skills. Same skill in .github/skills and .claude/skills may list twice (KB topics/skills.md).", "source": "tools/github-copilot.md §4; topics/skills.md" }, "skills.spec": { "level": "N", "native": "SKILL.md (name, description required)", "note": "VS Code name rules strict: invalid characters make the skill silently fail to load. Three-level progressive loading.", "source": "tools/github-copilot.md §4; https://code.visualstudio.com/docs/copilot/customization/agent-skills" }, "skills.extras": { "level": "N", "native": "allowed-tools; VS Code argument-hint, user-invocable, disable-model-invocation, context: fork", "note": "GitHub: license, allowed-tools. VS Code adds others; context: fork needs github.copilot.chat.skillTool.enabled.", "source": "tools/github-copilot.md §4" }, "commands.format": { "level": "P", "native": ".claude/commands/*.md (CLI); .github/prompts/*.prompt.md (VS Code Local)", "note": "Prompt files not loaded by Agent Host, deprecated; CLI reads .claude/commands, lower priority than same-name skills. No Copilot-native CLI command dir.", "source": "tools/github-copilot.md §5" }, "agents.profiles": { "level": "N", "native": ".github/agents/*.agent.md", "note": "Also org/enterprise .github-private and ~/.copilot/agents. Prompt body max 30,000 chars. Fields: description, name, target, tools, model, mcp-servers.", "source": "tools/github-copilot.md §6" }, "agents.tool-limits": { "level": "N", "native": "tools: frontmatter (aliases execute, read, edit, search, agent, web, todo)", "note": "Default all tools. todo alias not supported in cloud.", "source": "tools/github-copilot.md §6" }, "agents.cross-read": { "level": "C", "native": ".claude/agents/ (VS Code and CLI), ~/.claude/agents (VS Code)", "note": "CLI walks up to Git root; .github/agents beats .claude/agents at same level. CLI also documents plugin agents.", "source": "tools/github-copilot.md §6" }, "hooks.shell": { "level": "N", "native": ".github/hooks/*.json", "note": "14 events on CLI + Cloud; 8 on VS Code Local. Handlers: command, http, prompt. Cloud honours only bash/command.", "source": "tools/github-copilot.md §7" }, "hooks.session-start": { "level": "N", "native": "sessionStart / SessionStart", "note": "All interfaces with hooks. additionalContext supported; prompt handler fires only here.", "source": "tools/github-copilot.md §7" }, "hooks.tool-before": { "level": "N", "native": "preToolUse / PreToolUse", "note": "VS Code Local ignores matcher values, so every command runs; CLI and Cloud honour anchored regex matchers.", "source": "tools/github-copilot.md §7" }, "hooks.tool-after": { "level": "N", "native": "postToolUse / PostToolUse", "note": "Also postToolUseFailure (CLI/Cloud). Two spellings: camelCase or PascalCase with snake_case fields.", "source": "tools/github-copilot.md §7" }, "hooks.agent-stop": { "level": "N", "native": "agentStop / Stop", "note": "subagentStop also. CLI overrides a hook after 8 consecutive block continuations.", "source": "tools/github-copilot.md §7" }, "hooks.block": { "level": "N", "native": "permissionDecision: deny; exit 2", "note": "preToolUse and permissionRequest (CLI only). Under Cloud, ask is treated as deny.", "source": "tools/github-copilot.md §7" }, "hooks.inject-context": { "level": "P", "native": "additionalContext", "note": "sessionStart, subagentStart, postToolUse, notification, postToolUseFailure. Caps: 10 MiB; joined postToolUse context 10 KB. Hub marks P.", "source": "tools/github-copilot.md §7; cross-platform-ai-harness.md §4" }, "hooks.rewrite-input": { "level": "N", "native": "modifiedArgs (preToolUse)", "note": "Also VS Code updatedInput. modifiedPrompt honoured only by SDK hooks, not file hooks.", "source": "tools/github-copilot.md §7" }, "hooks.rewrite-output": { "level": "P", "native": "modifiedResult (postToolUse)", "note": "Documented for command/HTTP hooks, but issue copilot-cli#3361 says the model does not see it. Unproven; verify with a live test.", "source": "tools/github-copilot.md §7; open-questions.md Copilot output rewriting" }, "hooks.model-level": { "level": "-", "native": "", "note": "No before/after model-call hook in the 14 events.", "source": "tools/github-copilot.md §7" }, "hooks.inferential": { "level": "P", "native": "prompt handler", "note": "Fires only on sessionStart in new interactive CLI sessions; hub matrix shows P. Not a general inferential gate.", "source": "tools/github-copilot.md §7" }, "hooks.fail-closed": { "level": "P", "native": "preToolUse fail-closed on error", "note": "Non-zero/exit 2 denies preToolUse, but timeouts fail open for every event and HTTP preToolUse hooks fail open. CLI; policy hooks cannot be disabled.", "source": "tools/github-copilot.md §7; https://docs.github.com/en/copilot/reference/hooks-reference" }, "hooks.cross-read": { "level": "C", "native": "CLI reads .claude/settings.json; VS Code chat.useClaudeHooks", "note": "CLI reads repo .claude/settings(.local).json hooks; VS Code opt-in, off by default. PascalCase events use Claude-style matchers.", "source": "tools/github-copilot.md §7" }, "policy.rules": { "level": "P", "native": "--allow-tool / --deny-tool Kind(arg)", "note": "CLI flags: allow and deny only, no ask list (managed settings add deny/ask/allow arrays); deny beats allow even with --allow-all. VS Code uses chat.tools.terminal.autoApprove.", "source": "tools/github-copilot.md §8" }, "policy.repo": { "level": "P", "native": "VS Code workspace settings (chat.tools.*)", "note": "CLI flag rules are session-only; approvals saved in user-level permissions-config.json. No repo-committed CLI permission file documented in KB.", "source": "tools/github-copilot.md §8" }, "policy.sandbox": { "level": "P", "native": "CLI --sandbox; VS Code sandbox; Cloud firewall", "note": "Cloud firewall covers only agent bash-launched processes, not MCP servers or setup steps. VS Code sandbox on macOS/Linux MCP.", "source": "tools/github-copilot.md §8, §10" }, "policy.ignore": { "level": "P", "native": "Content exclusion (GitHub settings)", "note": "No local .copilotignore. Not honoured in VS Code Edit/Agent modes; honoured in CLI (since 2026-09-02) and Cloud (since 2026-06-30, preview). Not a security boundary.", "source": "tools/github-copilot.md §9" }, "policy.managed": { "level": "N", "native": "Org/enterprise policy, hook policy dir, content exclusion", "note": "Governance in GitHub org settings; CLI policy hooks in /etc/github-copilot/policy.d cannot be disabled; VS Code ChatAllowManagedHooksOnly.", "source": "tools/github-copilot.md §1, §7, §8" }, "mcp.client": { "level": "N", "native": "MCP client", "note": "All interfaces (CLI, VS Code, Cloud, Review). GitHub MCP server built in.", "source": "tools/github-copilot.md §10" }, "mcp.project-config": { "level": "N", "native": ".vscode/mcp.json + .mcp.json; CLI .mcp.json / .github/mcp.json", "note": "CLI does not read .vscode/mcp.json (root key servers is unsupported); CLI root key mcpServers. Cloud: repo settings on github.com.", "source": "tools/github-copilot.md §10" }, "mcp.remote": { "level": "N", "native": "type: http / sse, url, headers", "note": "VS Code and CLI. Cloud MCP supports tools only (resources/prompts verify).", "source": "tools/github-copilot.md §10" }, "intel.lsp": { "level": "P", "native": "CLI .github/lsp.json, ~/.copilot/lsp-config.json", "note": "CLI only (lspServers, fileExtensions). Plugin LSP path is inconsistent in docs; needs live test. VS Code has language-extension tools, no config.", "source": "tools/github-copilot.md §11; open-questions.md Copilot CLI LSP" }, "intel.memory": { "level": "N", "native": "Copilot Memory (GitHub-hosted)", "note": "Repo facts plus user preferences; cloud agent, review, CLI; 28-day expiry; admin-gated on Business/Enterprise. No local MEMORY file.", "source": "tools/github-copilot.md §13" }, "plugins.package": { "level": "N", "native": "plugin.json (Agent Plugins 1.0/1.1 or legacy)", "note": "VS Code and CLI; Copilot-specific parts under com.github.copilot/. Cloud loads no plugins.", "source": "tools/github-copilot.md §12" }, "plugins.marketplace": { "level": "N", "native": "marketplace.json; defaults copilot-plugins, awesome-copilot", "note": "CLI plugin install; VS Code chat.plugins.marketplaces. CLI also reads .claude-plugin/marketplace.json.", "source": "tools/github-copilot.md §12" }, "plugins.agent-plugins": { "level": "N", "native": "Agent Plugins 1.0 (plugin.json with $schema)", "note": "Supported by VS Code and CLI; root plugin.json takes precedence over legacy manifests. Only skills and mcp travel in the standard scope.", "source": "tools/github-copilot.md §12" }, "plugins.claude-manifest": { "level": "C", "native": ".claude-plugin/plugin.json", "note": "VS Code and CLI (CLI discovery since v1.0.6, MCP/LSP loading fixed v1.0.10). Whether ${CLAUDE_PLUGIN_ROOT} expands in skill bodies is unverified.", "source": "tools/github-copilot.md §12; open-questions.md" } } }, { "id": "cursor", "label": "Cursor", "reviewed": "2026-10-18", "headless": "agent -p", "homeDirs": [ ".cursor/", "~/.cursor/" ], "summary": "An IDE that reads Claude and Codex formats by default, including CLAUDE.md, skills, agents and hooks. After Claude it has the most hooks: 21 events, with failClosed per hook and prompt handlers. It also runs Cloud Agents.", "unique": [ { "title": "Per-action hook events", "detail": "beforeShellExecution, beforeReadFile, beforeMCPExecution, Tab hooks and afterAgentThought target an action type by event instead of a matcher.", "source": "tools/cursor.md §14; hub §6" }, { "title": "failClosed and loop_limit", "detail": "Each hook can choose to fail closed. loop_limit (default 5) caps the follow-up loops from stop and subagentStop.", "source": "tools/cursor.md §7, §14" }, { "title": "Apply Intelligently rules", "detail": "Description-activated rules, lighter than a skill, alongside globs, always and manual modes.", "source": "tools/cursor.md §3; hub §6" }, { "title": "sessionStart env injection", "detail": "A sessionStart hook can return an env object that sets environment variables for the session, plus additional_context.", "source": "tools/cursor.md §14" }, { "title": "Auto-review run mode", "detail": "Model-based classifier with plain-English allow_instructions and block_instructions in permissions.json; docs say it is not a security boundary.", "source": "tools/cursor.md §8, §14" }, { "title": "Cloud Agents environments", "detail": "Triggered from Slack, PR comments, Linear, API; environment defined in .cursor/environment.json; secrets in dashboard.", "source": "tools/cursor.md §14" }, { "title": "Team marketplaces", "detail": "Private plugin marketplaces with Default Off, Default On or Required, managed by Organization Groups.", "source": "tools/cursor.md §12" }, { "title": ".cursorignore breadth", "detail": "One ignore file also covers Tab, Inline Edit and @-mentions, though terminal and MCP bypass it.", "source": "tools/cursor.md §9; hub §6" } ], "gotchas": [ "Rules need the .mdc extension. A plain .md in .cursor/rules is silently ignored.", "CLAUDE.md and AGENTS.md are both always applied, so duplicated text loads twice.", "agent -p: the CLI usage page says full write access in non-interactive mode (Codex exec is read-only by default), but the headless page says changes are only proposed without --force (verify).", "Cloud Agents skip user hooks, sessionStart/sessionEnd, MCP hooks and Tab hooks.", "Claude Notification and PermissionRequest hooks do not run via Third-Party Imports, and matchers behave differently from Claude's.", "Old cursor.com/docs/context/* URLs return Page not found. Use /docs/rules, /docs/skills and /docs/mcp." ], "cells": { "surface.cli": { "level": "N", "native": "agent CLI (Agent/Plan/Ask modes)", "note": "Formerly cursor-agent (verify current). Install via curl script.", "source": "tools/cursor.md §2" }, "surface.ide": { "level": "N", "native": "Cursor IDE (VS Code fork)", "note": "Primary interface; rules, hooks, ignore and Tab features are IDE-centred.", "source": "tools/cursor.md §1" }, "surface.cloud": { "level": "N", "native": "Cloud Agents (background)", "note": "Triggered from Slack, PR comments, Linear, API; & prefix in CLI. Skips user hooks, session and MCP hooks.", "source": "tools/cursor.md §14, §7; https://cursor.com/docs/cloud-agent" }, "headless.run": { "level": "N", "native": "agent -p", "note": "--force/--yolo. Docs conflict: the CLI usage page says -p has full write access in non-interactive mode, the headless page says changes are only proposed without --force (verify). Key: CURSOR_API_KEY.", "source": "tools/cursor.md §2; topics/code-intelligence-memory-and-headless.md" }, "headless.json": { "level": "N", "native": "--output-format json|stream-json", "note": "Also text and --stream-partial-output. Structured-output schema flag not documented.", "source": "tools/cursor.md §2" }, "instr.agents-md": { "level": "N", "native": "AGENTS.md (root + nested)", "note": "Plain markdown, no frontmatter. Always applied.", "source": "tools/cursor.md §3; https://cursor.com/docs/rules" }, "instr.claude-md": { "level": "C", "native": "CLAUDE.md (project root)", "note": "IDE and CLI; always applied regardless of alwaysApply, so text duplicated with AGENTS.md loads twice. Nested and ~/.claude/CLAUDE.md unclear (verify).", "source": "tools/cursor.md §3; https://cursor.com/help/customization/rules" }, "instr.own-file": { "level": "N", "native": ".cursor/rules/*.mdc (alwaysApply: true)", "note": "Also User Rules (settings) and Team Rules (dashboard). Plain .md in rules dir is ignored.", "source": "tools/cursor.md §3" }, "instr.nested": { "level": "N", "native": "nested AGENTS.md", "note": "Read in subdirectories. Nested CLAUDE.md not documented (verify).", "source": "tools/cursor.md §3" }, "instr.imports": { "level": "?", "native": "", "note": "Inline @-imports not documented in KB; hub matrix lists '?'. @-mention applies rules manually, which is different.", "source": "cross-platform-ai-harness.md §4 matrix" }, "rules.glob": { "level": "N", "native": ".cursor/rules/*.mdc (globs)", "note": "Mode label 'Apply to Specific Files'. Frontmatter is description, globs, alwaysApply only. Rules under 500 lines.", "source": "tools/cursor.md §3" }, "rules.description": { "level": "N", "native": "'Apply Intelligently' (description only)", "note": "Agent decides from description; rule has no globs and alwaysApply false.", "source": "tools/cursor.md §3" }, "skills.agents-dir": { "level": "N", "native": ".agents/skills/, ~/.agents/skills/", "note": "Recursive; nested dirs and monorepo packages auto-scope.", "source": "tools/cursor.md §4; https://cursor.com/docs/skills" }, "skills.claude-dir": { "level": "C", "native": ".claude/skills/, ~/.claude/skills/", "note": "Also .codex/skills. Loaded alongside .cursor/skills, so same skill in two dirs may list twice (KB: topics/skills.md).", "source": "tools/cursor.md §4" }, "skills.spec": { "level": "N", "native": "SKILL.md, name must match folder", "note": "Implicit by description, /skill-name or @skill-name invocation.", "source": "tools/cursor.md §4" }, "skills.extras": { "level": "N", "native": "paths, disable-model-invocation, icon, color, metadata", "note": "paths is outside the Agent Skills spec; other hosts ignore it.", "source": "tools/cursor.md §4, §15" }, "commands.format": { "level": "N", "native": ".cursor/commands/*.md", "note": "Still supported, not deprecated; /migrate-to-skills converts to skills with disable-model-invocation.", "source": "tools/cursor.md §5; open-questions.md (resolved 2026-09-29)" }, "agents.profiles": { "level": "N", "native": ".cursor/agents/*.md", "note": "Fields name, description, model, readonly, is_background. Built-ins Explore and Browser (no Bash). Two nesting levels max.", "source": "tools/cursor.md §6; https://cursor.com/docs/subagents" }, "agents.tool-limits": { "level": "P", "native": "readonly: true", "note": "No tools allow-list field documented; only a readonly flag. Hook matcher can target subagent types.", "source": "tools/cursor.md §6" }, "agents.cross-read": { "level": "C", "native": ".claude/agents, .codex/agents", "note": "Also ~/ equivalents. Precedence .cursor over .claude over .codex; same names resolve by it.", "source": "tools/cursor.md §6, §15" }, "hooks.shell": { "level": "N", "native": ".cursor/hooks.json (21 events)", "note": "command and prompt handlers. Enterprise, team, project and user tiers. Cloud agents run a subset.", "source": "tools/cursor.md §7; https://cursor.com/docs/hooks" }, "hooks.session-start": { "level": "N", "native": "sessionStart", "note": "Can return env and additional_context. Not run in cloud agents.", "source": "tools/cursor.md §7" }, "hooks.tool-before": { "level": "N", "native": "preToolUse (+ beforeShellExecution, beforeReadFile, beforeMCPExecution)", "note": "Matcher is regex on tool type (Shell, Read, Write, Grep, Delete, Task, MCP:). Re-filter in core.", "source": "tools/cursor.md §7" }, "hooks.tool-after": { "level": "N", "native": "postToolUse (+ postToolUseFailure, afterShellExecution, afterFileEdit)", "note": "postToolUse can return additional_context and updated_mcp_tool_output.", "source": "tools/cursor.md §7" }, "hooks.agent-stop": { "level": "N", "native": "stop (+ subagentStop)", "note": "followup_message auto-submits a follow-up; loop_limit default 5 caps it.", "source": "tools/cursor.md §7" }, "hooks.block": { "level": "N", "native": "exit code 2 or permission: deny", "note": "Dedicated before* events for shell, MCP, file read. Other non-zero exit fails open unless failClosed.", "source": "tools/cursor.md §7" }, "hooks.inject-context": { "level": "P", "native": "additional_context", "note": "Only sessionStart, postToolUse, postToolUseFailure. Other events cannot inject; stop uses followup_message.", "source": "tools/cursor.md §7 (raw hooks page 2026-09-29)" }, "hooks.rewrite-input": { "level": "N", "native": "preToolUse updated_input", "note": "Documented in profile. Older context-mode source claims no updated_input; profile chosen (primary docs).", "source": "tools/cursor.md §7; topics/hooks.md gotchas" }, "hooks.rewrite-output": { "level": "P", "native": "postToolUse updated_mcp_tool_output", "note": "MCP tool output only, not general tool output rewriting.", "source": "tools/cursor.md §7; Differences table" }, "hooks.model-level": { "level": "-", "native": "", "note": "No before/after-model-call hooks. afterAgentThought and afterAgentResponse are observational only.", "source": "tools/cursor.md §7" }, "hooks.inferential": { "level": "N", "native": "type: prompt (LLM evaluates condition, returns {ok, reason?})", "note": "Local only; not supported in cloud agents.", "source": "tools/cursor.md §7" }, "hooks.fail-closed": { "level": "N", "native": "failClosed (per hook, default false)", "note": "Default is fail-open on non-0/2 exit. Unique per-hook option among the hosts.", "source": "tools/cursor.md §7" }, "hooks.cross-read": { "level": "C", "native": "Third-Party Imports: .claude/settings*.json", "note": "On by default. Maps 8 events; Notification and PermissionRequest unsupported; Glob has no mapping.", "source": "tools/cursor.md §7; https://cursor.com/docs/reference/third-party-hooks" }, "policy.rules": { "level": "N", "native": "cli.json Shell()/Read()/Write()/WebFetch()/Mcp() tokens", "note": "Deny beats allow. IDE uses run modes (Auto-review, Allowlist, Run Everything); no ask token in CLI list.", "source": "tools/cursor.md §8; https://cursor.com/docs/cli/reference/permissions" }, "policy.repo": { "level": "P", "native": ".cursor/cli.json, .cursor/sandbox.json", "note": "Repo-level for CLI and sandbox. IDE Auto-review permissions.json exists at user and project level (team config overrides); IDE allowlist is user-level.", "source": "tools/cursor.md §8" }, "policy.sandbox": { "level": "N", "native": "sandbox.json; --sandbox enabled|disabled", "note": "Seatbelt (macOS), Landlock/seccomp with Bubblewrap fallback (Linux); Windows not documented. Network modes; optional by default. Team-admin policy overrides.", "source": "tools/cursor.md §8; topics/policy-sandbox-and-ignore.md" }, "policy.ignore": { "level": "P", "native": ".cursorignore (gitignore syntax)", "note": "Covers Agent, Tab, Inline Edit and @ mentions but terminal and MCP tools bypass it. Not security.", "source": "tools/cursor.md §9; https://cursor.com/docs/reference/ignore-file" }, "policy.managed": { "level": "N", "native": "Team/Enterprise dashboard policy; enterprise hooks.json", "note": "Team-admin sandbox override, MCP allowlist, team marketplaces and enterprise hooks path.", "source": "tools/cursor.md §7, §8, §12" }, "mcp.client": { "level": "N", "native": "mcpServers", "note": "stdio, SSE and streamable HTTP. Tools ask approval by default.", "source": "tools/cursor.md §10; https://cursor.com/docs/mcp" }, "mcp.project-config": { "level": "N", "native": ".cursor/mcp.json", "note": "Global ~/.cursor/mcp.json. CLI reads the same file. Interpolates ${env:NAME}, ${workspaceFolder}.", "source": "tools/cursor.md §10" }, "mcp.remote": { "level": "N", "native": "url, headers, auth (OAuth)", "note": "Remote fields url/headers/auth with client id, secret, scopes.", "source": "tools/cursor.md §10" }, "intel.lsp": { "level": "-", "native": "", "note": "No model-facing LSP tool documented (verify). Has Instant Grep and Explore subagent (no semantic indexing on the search page); diagnostics IDE-internal.", "source": "tools/cursor.md §11" }, "intel.memory": { "level": "?", "native": "", "note": "Cursor once shipped Memories (stale?/verify); no current memory doc found. Persistence via rules and AGENTS.md.", "source": "tools/cursor.md §13; topics/code-intelligence-memory-and-headless.md" }, "plugins.package": { "level": "N", "native": ".cursor-plugin/plugin.json; root plugin.json", "note": "Cursor Plugins add rules, agents, commands, hooks beyond skills and MCP. Install via Customize page or Marketplace.", "source": "tools/cursor.md §12; https://cursor.com/docs/plugins" }, "plugins.marketplace": { "level": "N", "native": "Cursor Marketplace; team marketplaces", "note": "Private marketplaces with Default Off/On/Required via Organization Groups. Codex reads .cursor-plugin/marketplace.json.", "source": "tools/cursor.md §12" }, "plugins.agent-plugins": { "level": "N", "native": "root plugin.json (open standard)", "note": "Cursor is on the Agent Plugins TSC and listed as compatible client. Only skills and MCP travel across.", "source": "tools/cursor.md §12; topics/plugins-and-distribution.md; sources/agent-plugins-spec.md" }, "plugins.claude-manifest": { "level": "?", "native": "", "note": "Cursor imports third-party plugins by default via Third-Party Imports toggle, but .claude-plugin/ manifest reading is not documented; verification log lists only VS Code, Copilot CLI, Codex.", "source": "open-questions.md (Claude-plugin skills discovery); verification log" } } }, { "id": "gemini-cli", "label": "Gemini CLI", "reviewed": "2026-10-18", "headless": "gemini -p", "homeDirs": [ ".gemini/", "~/.gemini/", "GEMINI.md" ], "summary": "For enterprise and paid API keys only since consumer access ended on 2026-06-18. It has hooks at the model level (BeforeModel, AfterModel, BeforeToolSelection), a TOML policy engine with tiers, and remote subagents over A2A.", "unique": [ { "title": "Model-level hooks", "detail": "BeforeModel, AfterModel and BeforeToolSelection can override or mock requests, redact responses and filter the tool list. Claude has no equivalent.", "source": "cross-platform-ai-harness.md §6; tools/gemini-cli.md §7" }, { "title": "Tiered policy engine", "detail": "Numeric priorities, regex argsPattern, per-subagent rules and approval-mode scoping across default/extension/user/admin tiers. Workspace tier is non-functional.", "source": "cross-platform-ai-harness.md §6; tools/gemini-cli.md §8" }, { "title": "A2A remote subagents", "detail": "Subagents with kind: remote delegate to agents running elsewhere; @agentname forces delegation.", "source": "cross-platform-ai-harness.md §6; tools/gemini-cli.md §6" }, { "title": "Namespaced TOML commands", "detail": "Subdirs become :namespaces; !{cmd} runs shell with confirmation and @{path} embeds files, respecting ignore files.", "source": "tools/gemini-cli.md §5, §14" }, { "title": "Multi-backend sandbox", "detail": "GEMINI_SANDBOX selects Seatbelt, Docker, Podman, gVisor runsc or LXC; Windows native sandbox also available.", "source": "tools/gemini-cli.md §8" }, { "title": "Auto Memory (experimental)", "detail": "Mines transcripts and drafts .patch memory updates and SKILL.md files into a project inbox for review.", "source": "tools/gemini-cli.md §13" }, { "title": "Folder trust", "detail": "Untrusted folders skip project settings, .env, MCP servers and custom commands; extension installs blocked.", "source": "tools/gemini-cli.md §15" } ], "gotchas": [ "Consumer access (AI Pro/Ultra, free Code Assist) ended 2026-06-18. Google's word is 'transitioning', not 'successor'. Paid API keys and enterprise continue.", "The gemini-cli README still advertises a free tier, but the Google blog contradicts it. Trust the blog, and say the README looks out of date.", "Workspace policy TOML in .gemini/policies does not work (#18186), so a repo cannot ship policy.", "Hook exit codes: docs say exit 2 blocks, source says only exit 1 warns and other non-zero denies. Emit JSON and exit 0.", "Hook stdout must be pure JSON. Plain text breaks parsing, and the hook then defaults to allow.", ".geminiignore is advisory: shell, writes and fallback grep bypass it, and the model can opt out on most tools." ], "cells": { "surface.cli": { "level": "N", "native": "gemini (terminal CLI)", "note": "Only interface in KB. Consumer access ended 2026-06-18; paid API keys and Code Assist Standard/Enterprise continue.", "source": "tools/gemini-cli.md §1; https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/" }, "surface.ide": { "level": "-", "native": "", "note": "No IDE interface for the host in KB. Gemini Code Assist IDE extensions are a separate product; consumer tiers also stopped 2026-06-18.", "source": "cross-platform-ai-harness.md §3; sources/google-gemini-cli-to-antigravity-transition.md" }, "surface.cloud": { "level": "-", "native": "", "note": "No cloud/background agent documented for the CLI. Code Assist for GitHub is a separate product (consumer installs stop being served).", "source": "cross-platform-ai-harness.md §3; sources/google-gemini-cli-to-antigravity-transition.md" }, "headless.run": { "level": "N", "native": "gemini -p / --prompt", "note": "Non-TTY also triggers headless. Exit codes 0, 1, 42 (input error), 53 (turn limit). Enterprise/API key only after 2026-06-18.", "source": "tools/gemini-cli.md §2; https://geminicli.com/docs/cli/headless/" }, "headless.json": { "level": "N", "native": "--output-format json | stream-json", "note": "json gives {response, stats, error?}; stream-json is JSONL (init, message, tool_use, tool_result, error, result). No structured-output schema flag.", "source": "tools/gemini-cli.md §2; topics/code-intelligence-memory-and-headless.md" }, "instr.agents-md": { "level": "C", "native": "context.fileName: [\"AGENTS.md\",\"GEMINI.md\"]", "note": "Not read by default; add AGENTS.md to context.fileName in settings.json.", "source": "tools/gemini-cli.md §3; cross-platform-ai-harness.md §4 note 2" }, "instr.claude-md": { "level": "C", "native": "context.fileName: [\"CLAUDE.md\"]", "note": "Only via the configurable filename list; not read by default.", "source": "cross-platform-ai-harness.md §4 note 2; tools/gemini-cli.md §3" }, "instr.own-file": { "level": "N", "native": "GEMINI.md (~/.gemini/GEMINI.md + repo)", "note": "Global, workspace and parent dirs; memoryBoundaryMarkers default [\".git\"].", "source": "tools/gemini-cli.md §3; https://geminicli.com/docs/cli/gemini-md/" }, "instr.nested": { "level": "N", "native": "GEMINI.md just-in-time in subdirs", "note": "When a tool accesses a file, the CLI scans that dir and ancestors up to a trusted root for GEMINI.md.", "source": "tools/gemini-cli.md §3; verification log" }, "instr.imports": { "level": "N", "native": "@./file.md, @../shared/x.md", "note": "Relative and absolute paths; no documented depth or size limit.", "source": "tools/gemini-cli.md §3" }, "rules.glob": { "level": "-", "native": "", "note": "No glob-scoped rules (confirmed 2026-09-29). Use nested GEMINI.md instead.", "source": "tools/gemini-cli.md §3" }, "rules.description": { "level": "-", "native": "", "note": "No description-activated rules (confirmed 2026-09-29). A skill is the equivalent.", "source": "tools/gemini-cli.md §3" }, "skills.agents-dir": { "level": "N", "native": ".agents/skills/ (workspace), ~/.agents/skills/ (user)", "note": "Alias wins over .gemini/skills within the same tier; extension and built-in tiers rank lower.", "source": "tools/gemini-cli.md §4; https://geminicli.com/docs/cli/skills/" }, "skills.claude-dir": { "level": "-", "native": "", "note": "No .claude/skills discovery documented.", "source": "tools/gemini-cli.md §4" }, "skills.spec": { "level": "N", "native": "SKILL.md via activate_skill", "note": "Name+description in system prompt, model calls activate_skill after user consent, then body is injected. gemini skills install|list.", "source": "tools/gemini-cli.md §4" }, "skills.extras": { "level": "?", "native": "", "note": "Frontmatter beyond name/description not documented in the fetch (verify). Hub matrix says extras are ignored.", "source": "tools/gemini-cli.md §4 (verify); cross-platform-ai-harness.md §5" }, "commands.format": { "level": "N", "native": ".gemini/commands/*.toml", "note": "TOML with prompt/description; subdir becomes :namespace; {{args}}, !{cmd}, @{path}. Not deprecated; not loaded in untrusted folders.", "source": "tools/gemini-cli.md §5; https://geminicli.com/docs/cli/custom-commands/" }, "agents.profiles": { "level": "N", "native": ".gemini/agents/*.md (project), ~/.gemini/agents/", "note": "Markdown + YAML: name, description, kind local|remote (A2A), tools, mcpServers, model, temperature, max_turns, timeout_mins.", "source": "tools/gemini-cli.md §6; https://geminicli.com/docs/core/subagents/" }, "agents.tool-limits": { "level": "N", "native": "tools: [...] (wildcards *, mcp_*)", "note": "Per-agent tools array; inline mcpServers isolated to the agent.", "source": "tools/gemini-cli.md §6" }, "agents.cross-read": { "level": "-", "native": "", "note": "Does not read .claude/agents or .codex/agents (not shown in KB cross-read notes).", "source": "cross-platform-ai-harness.md §4 (agent profiles row); tools/gemini-cli.md §6" }, "hooks.shell": { "level": "N", "native": "hooks in settings.json (11 events)", "note": "type command; timeout ms (default 60000); regex matcher for tool events. Includes model-level events. Manage via /hooks.", "source": "tools/gemini-cli.md §7; https://geminicli.com/docs/hooks/" }, "hooks.session-start": { "level": "N", "native": "SessionStart", "note": "Fires on startup, resume, clear; can inject context.", "source": "tools/gemini-cli.md §7" }, "hooks.tool-before": { "level": "N", "native": "BeforeTool", "note": "Regex matcher on tool name (e.g. run_shell_command); can block or rewrite args.", "source": "tools/gemini-cli.md §7" }, "hooks.tool-after": { "level": "N", "native": "AfterTool", "note": "Can replace result (deny + reason), add context, or chain a tail tool call.", "source": "tools/gemini-cli.md §7" }, "hooks.agent-stop": { "level": "N", "native": "AfterAgent", "note": "Nearest equivalent: fires when the agent loop is done; deny forces a retry with reason as prompt. SessionEnd is advisory only.", "source": "tools/gemini-cli.md §7" }, "hooks.block": { "level": "N", "native": "decision:\"deny\" + reason (BeforeTool)", "note": "Also continue:false kills the loop. Exit-code behaviour disputed (see fail-closed).", "source": "tools/gemini-cli.md §7; topics/hooks.md block row" }, "hooks.inject-context": { "level": "N", "native": "hookSpecificOutput.additionalContext", "note": "On SessionStart, BeforeAgent, AfterTool.", "source": "tools/gemini-cli.md §7" }, "hooks.rewrite-input": { "level": "N", "native": "hookSpecificOutput.tool_input (BeforeTool)", "note": "Merged with and overrides the tool args.", "source": "tools/gemini-cli.md §7" }, "hooks.rewrite-output": { "level": "P", "native": "AfterTool decision:deny replaces result", "note": "Documented: replace result with reason, add context. Direct output rewrite only asserted by context-mode; hub matrix shows P with footnote 8. Not upgraded beyond P.", "source": "tools/gemini-cli.md §7; topics/hooks.md rewrite-output row" }, "hooks.model-level": { "level": "N", "native": "BeforeModel, AfterModel, BeforeToolSelection", "note": "Override llm_request, return synthetic response, redact, filter tool list. Unique among core hosts.", "source": "tools/gemini-cli.md §7, §14; cross-platform-ai-harness.md §6" }, "hooks.inferential": { "level": "-", "native": "", "note": "Only type \"command\" documented; no prompt/agent handlers.", "source": "tools/gemini-cli.md §7" }, "hooks.fail-closed": { "level": "?", "native": "", "note": "Docs: exit 2 blocks, others warn. Source (fe63502): only exit 1 warns; any other non-zero with text denies. Unparseable stdout allows. Open question.", "source": "tools/gemini-cli.md §7; open-questions.md Gemini hook exit codes" }, "hooks.cross-read": { "level": "-", "native": "", "note": "Does not read Claude hooks. Only sets CLAUDE_PROJECT_DIR as an env alias for scripts.", "source": "tools/gemini-cli.md §7" }, "policy.rules": { "level": "N", "native": "Policy engine TOML: allow | deny | ask_user", "note": "toolName, argsPattern regex, commandPrefix, subagent, modes, priority 0-999; tiered. --allowed-tools and --yolo deprecated.", "source": "tools/gemini-cli.md §8; https://geminicli.com/docs/reference/policy-engine/" }, "policy.repo": { "level": "-", "native": ".gemini/policies/*.toml (non-functional)", "note": "Workspace tier is documented as currently non-functional (issue #18186). Only user and admin tiers work, so a repo cannot ship policy.", "source": "tools/gemini-cli.md §8, §15; verification log" }, "policy.sandbox": { "level": "N", "native": "-s / GEMINI_SANDBOX / tools.sandbox", "note": "Seatbelt profiles, Docker/Podman, Windows native, gVisor runsc, LXC (experimental). Off by default; the config reference says yolo mode enables it.", "source": "tools/gemini-cli.md §8; https://geminicli.com/docs/cli/sandbox/" }, "policy.ignore": { "level": "P", "native": ".geminiignore", "note": "Honoured by read_file, glob, ls, read_many_files, ripgrep grep; model can opt out on most. Not applied to shell, writes or fallback grep.", "source": "tools/gemini-cli.md §9" }, "policy.managed": { "level": "N", "native": "Admin policy tier (/etc/gemini-cli/policies)", "note": "Tier base 5, highest priority. macOS /Library/Application Support/GeminiCli/policies; also /etc/gemini-cli/settings.json.", "source": "tools/gemini-cli.md §8; topics/policy-sandbox-and-ignore.md" }, "mcp.client": { "level": "N", "native": "mcpServers in settings.json", "note": "stdio, SSE (url), streamable HTTP (httpUrl); includeTools/excludeTools, trust; gemini mcp add|list|remove.", "source": "tools/gemini-cli.md §10; https://geminicli.com/docs/tools/mcp-server/" }, "mcp.project-config": { "level": "N", "native": ".gemini/settings.json (mcpServers)", "note": "Inline in project settings; not loaded in untrusted folders. Interpolates $VAR, ${VAR}. Avoid underscores in server names.", "source": "tools/gemini-cli.md §10, §15" }, "mcp.remote": { "level": "N", "native": "url (SSE) / httpUrl (streamable HTTP)", "note": "headers, oauth, authProviderType supported. Antigravity uses serverUrl instead.", "source": "tools/gemini-cli.md §10; sources/google-gemini-cli-to-antigravity-transition.md" }, "intel.lsp": { "level": "-", "native": "", "note": "No LSP tool documented; built-in codebase_investigator subagent only (verify).", "source": "tools/gemini-cli.md §11" }, "intel.memory": { "level": "N", "native": "GEMINI.md memory tiers + experimental Auto Memory", "note": "Markdown tiers edited by write_file/replace; save_memory removed. Auto Memory (experimental) drafts patches into an inbox.", "source": "tools/gemini-cli.md §13" }, "plugins.package": { "level": "N", "native": "Extensions: gemini-extension.json", "note": "Bundles MCP, commands, skills, hooks, subagents, context, themes, settings, policies. Install from GitHub URL.", "source": "tools/gemini-cli.md §12; https://geminicli.com/docs/extensions/" }, "plugins.marketplace": { "level": "P", "native": "geminicli.com/extensions gallery", "note": "Gallery only, no marketplace file; install from GitHub URL or local path. security.blockGitExtensions for org control.", "source": "tools/gemini-cli.md §12; topics/plugins-and-distribution.md" }, "plugins.agent-plugins": { "level": "-", "native": "", "note": "Not on the Agent Plugins compatible-clients list (VS Code, Cursor, Copilot, Codex, Kiro and others).", "source": "sources/agent-plugins-spec.md" }, "plugins.claude-manifest": { "level": "-", "native": "", "note": "Uses its own gemini-extension.json; no .claude-plugin/ reading documented.", "source": "topics/plugins-and-distribution.md manifest path row; tools/gemini-cli.md §12" } } }, { "id": "antigravity", "label": "Antigravity", "reviewed": "2026-10-18", "headless": "agy -p", "homeDirs": [ "~/.gemini/config/", "~/.gemini/antigravity-cli/", "~/.gemini/antigravity-ide/", "~/.gemini/antigravity/" ], "summary": "Google's tool for consumers moving off Gemini CLI. Workspace config lives in .agents/: rules, skills, agents, hooks.json and mcp_config.json. It has six hook events and user-level permissions only, is closed source, and its three surfaces use different global folders.", "unique": [ { "title": "Loop-scripting hooks", "detail": "PreInvocation/PostInvocation injectSteps (tool calls, user or ephemeral messages) and terminationBehavior (force_continue/terminate). Stop can force the agent to keep going.", "source": "tools/antigravity.md §7, §14" }, { "title": "Richer permission decisions", "detail": "PreToolUse decisions include auto_approve, force_ask and deny_unless_prior_grant, plus permissionOverrides and overwrite, beyond allow/deny/ask.", "source": "tools/antigravity.md §7" }, { "title": "Four rule activation modes", "detail": "always_on, model_decision, glob and manual (@-mention) in .agents/rules, with a 24 KB per-file and 20k-token shared budget.", "source": "tools/antigravity.md §3" }, { "title": "Async multi-agent orchestration", "detail": "invoke_subagent, /boost, git-worktree branch workspaces, nesting depth 10, transient agents via define_subagent, subagent hooks: frontmatter (2.0 v2.17.0).", "source": "tools/antigravity.md §6, §14" }, { "title": "Structured headless I/O", "detail": "--json-schema output and stream-json input for continuous headless sessions; status envelope with usage and conversation_id.", "source": "tools/antigravity.md §2, §14" }, { "title": "Knowledge Items and artifacts", "detail": "IDE/2.0 auto-extracted persistent memory (KIs), artifacts, browser agent with recordings, voice dictation.", "source": "tools/antigravity.md §13, §14" }, { "title": "Gemini migration path", "detail": "agy plugin import gemini and /migrate-workflows; plugin sync between the 2.0 app and the CLI.", "source": "tools/antigravity.md §5, §12, §14" } ], "gotchas": [ "Hooks and MCP live under .agents/ (hooks.json, mcp_config.json), not .gemini/. Do not reuse a Gemini CLI settings.json hook or MCP block.", "Permissions are user-level only (~/.gemini/antigravity-cli/settings.json). A repo cannot ship allow/deny rules, so committed guards need a gate elsewhere.", "Rules with missing frontmatter or a camelCase trigger (alwaysOn) are silently discarded. Subfolders of .agents/rules are ignored without .agents/rules.json.", "PreInvocation/PostInvocation are per model call, not prompt-submit or stop. SessionStart runs once at session initialization, but the hook payload omits the event name.", "Global skill and hook folders differ per surface (antigravity-cli vs config). Remote MCP needs serverUrl, not url or httpUrl.", "Do not say Gemini CLI is dead. Consumer access ended 2026-06-18, but paid API keys and enterprise continue, and Google says 'transitioning'." ], "cells": { "surface.cli": { "level": "N", "native": "agy (Go TUI)", "note": "Lightweight TUI surface; works over SSH/tmux. Closed source (verify). Binary agy, changelog repo google-antigravity/antigravity-cli.", "source": "tools/antigravity.md §1, §2" }, "surface.ide": { "level": "N", "native": "Antigravity IDE (VS Code fork) + 2.0 desktop app", "note": "IDE and 2.0 app share ~/.gemini/config but have separate app dirs. Extensions for other editors are (verify).", "source": "tools/antigravity.md §2" }, "surface.cloud": { "level": "?", "native": "", "note": "No cloud or background agent is documented in the KB profile. Not documented in KB.", "source": "tools/antigravity.md §2 (absent)" }, "headless.run": { "level": "N", "native": "agy -p / --print / --prompt", "note": "Needs prior interactive login. Approval-needing tools are soft-denied unless allowed in settings.json or --dangerously-skip-permissions.", "source": "tools/antigravity.md §2; https://antigravity.google/docs/cli/headless/" }, "headless.json": { "level": "N", "native": "--output-format json|stream-json; --json-schema", "note": "Envelope: conversation_id, status, usage, response. Errors as AGY_ERROR JSON lines on stderr. stream-json input also supported.", "source": "tools/antigravity.md §2; topics/code-intelligence-memory-and-headless.md (Headless)" }, "instr.agents-md": { "level": "N", "native": "AGENTS.md (also .agents/AGENTS.md)", "note": "Read natively, always on for its directory scope, no frontmatter and no setting needed.", "source": "tools/antigravity.md §3" }, "instr.claude-md": { "level": "?", "native": "", "note": "Not documented in KB. Hub matrix marks it unverified; do not claim CLAUDE.md is read.", "source": "cross-platform-ai-harness.md §4 matrix" }, "instr.own-file": { "level": "N", "native": "GEMINI.md; ~/.gemini/GEMINI.md", "note": "GEMINI.md accepted alongside AGENTS.md, at root or in subdirectories; also .agents/GEMINI.md. Global under ~/.gemini/ and ~/.gemini/config/.", "source": "tools/antigravity.md §3" }, "instr.nested": { "level": "N", "native": "AGENTS.md / GEMINI.md / .agents/rules per directory", "note": "Walks up from each read or edited file to the workspace root, cumulative; more specific directory wins.", "source": "tools/antigravity.md §3; verification log" }, "instr.imports": { "level": "P", "native": "@[label](path) in rules", "note": "Documented in rules.md only. Imports in GEMINI.md/AGENTS.md remain unverified in the topic doc.", "source": "tools/antigravity.md §3; topics/instructions-and-rules.md Open questions" }, "rules.glob": { "level": "N", "native": ".agents/rules/*.md with trigger: glob, globs:", "note": "Singular glob: also accepted. Flat scan only; nested dirs need .agents/rules.json. Bad trigger is silently discarded.", "source": "tools/antigravity.md §3; https://antigravity.google/docs/rules" }, "rules.description": { "level": "N", "native": "trigger: model_decision + description", "note": "Path and description are shown up front, body loaded on demand. description is required. Other triggers: always_on, manual.", "source": "tools/antigravity.md §3" }, "skills.agents-dir": { "level": "N", "native": ".agents/skills//SKILL.md", "note": "Default on all surfaces; legacy .agent/skills still works. Global path differs: CLI ~/.gemini/antigravity-cli/skills, IDE/2.0 ~/.gemini/config/skills.", "source": "tools/antigravity.md §4" }, "skills.claude-dir": { "level": "?", "native": "", "note": "Discovery of .claude/skills is not documented. Listed as an open item.", "source": "tools/antigravity.md §4; topics/skills.md Open questions" }, "skills.spec": { "level": "N", "native": "SKILL.md, progressive disclosure", "note": "description required, name optional (defaults to folder). Optional scripts/, examples/, resources/. Autonomous or manual /.", "source": "tools/antigravity.md §4" }, "skills.extras": { "level": "?", "native": "", "note": "Frontmatter fields beyond name/description are undocumented (verify).", "source": "tools/antigravity.md §4; topics/skills.md Open questions" }, "commands.format": { "level": "P", "native": "Workflows (IDE/2.0), /workflow-name", "note": "Markdown, 12,000-char limit; current workflows stop working 2026-10-19 (docs changed from a 2026-11-01 deprecation); /migrate-workflows converts to skills. CLI has no command file format; skills are the slash commands.", "source": "tools/antigravity.md §5; https://antigravity.google/docs/ide/workflows/" }, "agents.profiles": { "level": "N", "native": ".agents/agents/.md or /agent.md", "note": "Frontmatter name, description, mainAgent, subagent, model, commandExecutionPolicy. Async and parallel; nesting depth 10. Global ~/.gemini/config/agents/.", "source": "tools/antigravity.md §6" }, "agents.tool-limits": { "level": "N", "native": "tools: [view_file, run_command, ...]", "note": "String list of tool names. A misspelled tool may hang the subagent process.", "source": "tools/antigravity.md §6" }, "agents.cross-read": { "level": "?", "native": "", "note": "Reading other hosts' agent folders is not documented. APM also lists agents as unsupported for Antigravity.", "source": "tools/antigravity.md §6; topics/agents-and-commands.md" }, "hooks.shell": { "level": "N", "native": ".agents/hooks.json (6 events)", "note": "Six events: SessionStart, PreToolUse, PostToolUse, PreInvocation, PostInvocation, Stop. Command handlers only; timeout in seconds (default 30). Global ~/.gemini/config/hooks.json.", "source": "tools/antigravity.md §7; verification log" }, "hooks.session-start": { "level": "N", "native": "SessionStart", "note": "Fires once at session start, before the first model call. Output is injectSteps (e.g. a systemMessage).", "source": "tools/antigravity.md §7; topics/hooks.md event table" }, "hooks.tool-before": { "level": "N", "native": "PreToolUse (matcher)", "note": "Matcher: empty, exact name, pipe list or regex over tool names like run_command. Payload lacks the event name.", "source": "tools/antigravity.md §7" }, "hooks.tool-after": { "level": "N", "native": "PostToolUse", "note": "Output is {}; carries an error field. Cannot alter the result.", "source": "tools/antigravity.md §7" }, "hooks.agent-stop": { "level": "N", "native": "Stop", "note": "Fires when the execution loop ends. decision 'continue' plus reason re-enters the loop. PostInvocation is per model call, not loop end.", "source": "tools/antigravity.md §7; topics/hooks.md" }, "hooks.block": { "level": "N", "native": "PreToolUse decision: deny|ask|force_ask|deny_unless_prior_grant", "note": "Blocking is by JSON decision on stdout. The exit-code contract is undocumented (all 89 pages checked).", "source": "tools/antigravity.md §7" }, "hooks.inject-context": { "level": "N", "native": "injectSteps (SessionStart / Pre/PostInvocation)", "note": "Injects systemMessage at session start, or tool calls, user messages or ephemeral messages into the loop. Different shape from additionalContext elsewhere.", "source": "tools/antigravity.md §7, §14" }, "hooks.rewrite-input": { "level": "N", "native": "overwrite in PreToolUse", "note": "PreToolUse may return overwrite: replacement arguments shallow-merged into toolCall.args before execution; a notice of changed keys is prepended to the result.", "source": "tools/antigravity.md §7; topics/hooks.md outputs table" }, "hooks.rewrite-output": { "level": "-", "native": "", "note": "PostToolUse returns {}; no output rewriting.", "source": "tools/antigravity.md §7; topics/hooks.md outputs table" }, "hooks.model-level": { "level": "P", "native": "PreInvocation / PostInvocation", "note": "Per model call, but can only inject steps or terminate; no request or response rewriting. Closer to Gemini BeforeModel/AfterModel in position only.", "source": "tools/antigravity.md §7; cross-platform-ai-harness.md §4" }, "hooks.inferential": { "level": "-", "native": "", "note": "Only type: command handlers are documented.", "source": "tools/antigravity.md §7" }, "hooks.fail-closed": { "level": "?", "native": "", "note": "No fail-closed switch; timeout and exit-code behaviour undocumented. 2.0 v2.12.0: a failing hook is reported and the session continues (2.0 app only).", "source": "tools/antigravity.md §7; topics/hooks.md exit codes table" }, "hooks.cross-read": { "level": "-", "native": "", "note": "Does not read Claude hook config. agy plugin import gemini converts extensions, not Gemini hooks.", "source": "topics/hooks.md cross-tool loading table" }, "policy.rules": { "level": "N", "native": "permissions allow/ask/deny: command(...), read_file, write_file, read_url, execute_url, mcp", "note": "Deny > Ask > Allow. Defaults: workspace files allowed; outside files, web and unconfigured commands ask. toolPermission modes incl. strict.", "source": "tools/antigravity.md §8; https://antigravity.google/docs/permissions" }, "policy.repo": { "level": "-", "native": "", "note": "User-level only: ~/.gemini/antigravity-cli/settings.json. Per-project overrides exist only in the 2.0 UI (Settings > Projects), documented for the permission preset. A repo cannot ship allow/deny rules.", "source": "tools/antigravity.md §8, §15; verification log" }, "policy.sandbox": { "level": "P", "native": "enableTerminalSandbox", "note": "Seatbelt (macOS), nsjail/namespaces (Linux); Windows keeps older behaviour. On by default in the 2.0 app on macOS/Linux, off in CLI and IDE. Linux backend wording conflicts.", "source": "tools/antigravity.md §8; open-questions.md (Antigravity sandbox default)" }, "policy.ignore": { "level": "?", "native": ".antigravityignore (changelog only)", "note": "No docs page documents an ignore file. Changelog v1.1.16 shows it affects @ completion; agent-tool coverage unknown. Use deny read_file(...) rules.", "source": "tools/antigravity.md §9; open-questions.md Antigravity" }, "policy.managed": { "level": "?", "native": "", "note": "2.0 v2.5.0 changelog: \"Added enterprise admin policies for browser features, MCP allowlists, and permission thresholds\"; location and format undocumented. Topic doc lists Antigravity as having none.", "source": "tools/antigravity.md §8; https://antigravity.google/docs/changelog (2.0 v2.5.0)" }, "mcp.client": { "level": "N", "native": "mcpServers in mcp_config.json", "note": "Global ~/.gemini/config/mcp_config.json shared by 2.0, IDE and CLI. /mcp manager. Permission action mcp(server/tool).", "source": "tools/antigravity.md §10" }, "mcp.project-config": { "level": "N", "native": ".agents/mcp_config.json", "note": "Not .gemini/settings.json (that is Gemini CLI). Fields command/args/env/cwd; disabledTools, disabled.", "source": "tools/antigravity.md §10; verification log" }, "mcp.remote": { "level": "N", "native": "serverUrl", "note": "Streamable HTTP/SSE/websocket via serverUrl only; url and httpUrl are not supported. headers, oauth, authProviderType available.", "source": "tools/antigravity.md §10; topics/mcp.md" }, "intel.lsp": { "level": "-", "native": "", "note": "No LSP tool documented (verify). Has /codesearch and IDE indexing; MCP wrapper is the route.", "source": "tools/antigravity.md §11; topics/code-intelligence-memory-and-headless.md" }, "intel.memory": { "level": "P", "native": "Knowledge Items (KIs)", "note": "IDE/2.0 only; auto-extracted from conversations. Official page is now removed (archived 2026-05-27); CLI docs silent. Hub matrix shows P.", "source": "tools/antigravity.md §13" }, "plugins.package": { "level": "N", "native": "plugin.json + skills/, agents/, rules/, hooks.json, mcp_config.json", "note": "Own schema (antigravity.google/schemas/v1). agy plugin install|list|enable|disable|uninstall; agy plugin import gemini. No commands/policies component documented.", "source": "tools/antigravity.md §12" }, "plugins.marketplace": { "level": "P", "native": "/plugin Discover tab", "note": "Marketplace documented for the 2.0 app and the CLI (/plugin Discover tab, antigravity-plugins-official); no marketplace file format in the KB.", "source": "tools/antigravity.md §12; topics/plugins-and-distribution.md" }, "plugins.agent-plugins": { "level": "-", "native": "", "note": "Not in the Agent Plugins compatible-clients list; uses its own plugin.json schema instead.", "source": "sources/agent-plugins-spec.md; tools/antigravity.md §12" }, "plugins.claude-manifest": { "level": "-", "native": "", "note": "Verification log lists VS Code, Copilot CLI and Codex as accepting a Claude manifest; Antigravity is not among them.", "source": "verification log" } } }, { "id": "opencode", "label": "OpenCode", "reviewed": "2026-10-18", "headless": "opencode run", "homeDirs": [ "~/.config/opencode/", "~/.claude/ (read)", "~/.agents/ (read)", "~/.local/share/opencode/" ], "summary": "An open-source TUI that can run as a client and a server. Hooks are JS/TS plugins that run in-process, not shell commands. It reads AGENTS.md and falls back to CLAUDE.md and .claude/skills. No triggered rules, sandbox or marketplace.", "unique": [ { "title": "Plugins as code", "detail": "In-process JS/TS plugins with an SDK client, Bun shell, event bus and shell.env injection. No process is spawned per hook.", "source": "tools/opencode.md §14" }, { "title": "Client/server architecture", "detail": "`opencode serve`/`web` with `--attach` lets run/TUI clients share a running server; auth via OPENCODE_SERVER_PASSWORD.", "source": "tools/opencode.md §2" }, { "title": "Remote instructions and org config", "detail": "`instructions` accepts URLs (5 s timeout) and globs, and a remote .well-known/opencode supplies org defaults.", "source": "tools/opencode.md §3, §12" }, { "title": "Broad built-in LSP set", "detail": "34 language servers listed, most of them installed automatically and configurable via `lsp`. The lsp tool the model uses is experimental.", "source": "tools/opencode.md §11" }, { "title": "Custom tools", "detail": "Custom tools live in .opencode/tools/ and plugin tools register as _.", "source": "tools/opencode.md §14" }, { "title": "Auto-approve flag", "detail": "`opencode run --auto` approves all non-denied permissions for unattended runs.", "source": "tools/opencode.md §2" }, { "title": "Env kill switches for Claude reads", "detail": "OPENCODE_DISABLE_CLAUDE_CODE, _PROMPT, _SKILLS turn off .claude cross-reads to avoid double loading.", "source": "tools/opencode.md §3" } ], "gotchas": [ "Silently reads CLAUDE.md and .claude/skills unless kill-switch env vars are set, so harnesses can double-load.", "No triggered rules: `instructions` globs only select files that are then always loaded.", "Nested AGENTS.md loading is upward only; downward or read-triggered loading is undocumented code behaviour.", "Permission rules are last-match-wins, the opposite ordering of Claude's fixed deny > ask > allow.", "No shell hooks: guards must be JS plugins that throw. The `permission.ask` hook may never fire, and SessionStart is reportedly broken.", "MCP `timeout` (5000 ms default) applies to fetching the tool list, not per call." ], "cells": { "surface.cli": { "level": "N", "native": "opencode (TUI)", "note": "Open-source terminal TUI; also `opencode serve` / `opencode web` HTTP servers with `--attach`.", "source": "tools/opencode.md §1-2" }, "surface.ide": { "level": "P", "native": "IDE extension (opens the TUI in a terminal)", "note": "IDE docs page: extension auto-installs for VS Code, Cursor, Windsurf, VSCodium when you run `opencode` in the integrated terminal; shares selection/tab and file references. It is a terminal wrapper, not a native panel.", "source": "tools/opencode.md §1; https://opencode.ai/docs/ide/" }, "surface.cloud": { "level": "P", "native": "opencode github install|run", "note": "Only GitHub Actions integration documented; no hosted cloud agent in KB.", "source": "tools/opencode.md §1-2" }, "headless.run": { "level": "N", "native": "opencode run", "note": "Flags: --agent, --command, -c/-s, --fork, --attach; --auto approves non-denied permissions.", "source": "tools/opencode.md §2; https://opencode.ai/docs/cli/" }, "headless.json": { "level": "N", "native": "opencode run --format json", "note": "`--format json` emits raw events.", "source": "tools/opencode.md §2" }, "instr.agents-md": { "level": "N", "native": "AGENTS.md", "note": "Project (walks up tree) and global ~/.config/opencode/AGENTS.md; /init generates it.", "source": "tools/opencode.md §3; https://opencode.ai/docs/rules/" }, "instr.claude-md": { "level": "C", "native": "CLAUDE.md, ~/.claude/CLAUDE.md", "note": "Fallback only if no AGENTS.md; first match per category wins. Disable with OPENCODE_DISABLE_CLAUDE_CODE=1.", "source": "tools/opencode.md §3" }, "instr.own-file": { "level": "-", "native": "", "note": "No host-specific always-on file; AGENTS.md is the native one. `instructions` array in opencode.json adds files, globs, URLs.", "source": "tools/opencode.md §3" }, "instr.nested": { "level": "P", "native": "AGENTS.md (walk up only)", "note": "Docs describe only upward walk from cwd. Read-triggered subdirectory loading exists in code, undocumented.", "source": "tools/opencode.md §3; verification log" }, "instr.imports": { "level": "-", "native": "", "note": "No native @import; docs suggest telling the model to lazy-load `@docs/x.md`.", "source": "tools/opencode.md §3" }, "rules.glob": { "level": "-", "native": "", "note": "No glob-scoped rules; `instructions` globs only select files that are then always loaded.", "source": "tools/opencode.md §3; hub §4 note 4" }, "rules.description": { "level": "-", "native": "", "note": "No description-activated rule format.", "source": "tools/opencode.md §3" }, "skills.agents-dir": { "level": "N", "native": "`.agents/skills/`, ~/.agents/skills/", "note": "Loaded alongside .opencode/ and .claude/ roots while walking up to the git worktree.", "source": "tools/opencode.md §4; https://opencode.ai/docs/skills/" }, "skills.claude-dir": { "level": "C", "native": "`.claude/skills/`, ~/.claude/skills/", "note": "Read by default; Loaded side by side (resolved from code 2026-09-29); the rules page's 'fallback' wording is stale. Kill switch OPENCODE_DISABLE_CLAUDE_CODE_SKILLS.", "source": "tools/opencode.md §4, §15; open-questions.md" }, "skills.spec": { "level": "N", "native": "SKILL.md via `skill` tool", "note": "name (regex, must equal dir), description, license, compatibility, metadata (string map). Own root `.opencode/skills/`. Older docs said unknown fields are ignored; current docs say to put OpenCode-specific behaviour in metadata.", "source": "tools/opencode.md §4" }, "skills.extras": { "level": "-", "native": "", "note": "Docs (2026-10-11) define metadata keys opencode/slash and opencode/autoinvoke (docs-only, verify in code); earlier text said only spec fields are recognised. Level left at none pending a code check.", "source": "tools/opencode.md §4" }, "commands.format": { "level": "N", "native": ".opencode/commands/*.md", "note": "Frontmatter description, agent, model, subtask; $ARGUMENTS, $1, !`cmd`, @file. Also `command` key in opencode.json.", "source": "tools/opencode.md §5" }, "agents.profiles": { "level": "N", "native": ".opencode/agents/*.md", "note": "Primary and subagent modes; built-in build, plan, general, explore, scout. Fields include mode, model, permission, steps.", "source": "tools/opencode.md §6" }, "agents.tool-limits": { "level": "N", "native": "`permission` per agent", "note": "`tools` field deprecated and converted to `permission`; `skill: false` disables the skill tool.", "source": "tools/opencode.md §6" }, "agents.cross-read": { "level": "-", "native": "", "note": "No .claude/agents or .codex/agents cross-read documented; Claude compatibility covers CLAUDE.md and skills only.", "source": "tools/opencode.md §6" }, "hooks.shell": { "level": "P", "native": "JS/TS plugins (no shell hooks)", "note": "No shell-command hooks: hooks are in-process JS/TS plugins (the hub matrix counts this as partial). In-process plugin functions, not stdin/stdout JSON commands. Hooks exist, so shell-hook reuse is not possible.", "source": "tools/opencode.md §7; hub §4" }, "hooks.session-start": { "level": "P", "native": "`session.created` (event hook)", "note": "context-mode reports SessionStart broken (issues #14808, #5409); surrogate experimental.chat.system.transform.", "source": "tools/opencode.md §7; topics/hooks.md events table" }, "hooks.tool-before": { "level": "N", "native": "`tool.execute.before`", "note": "input {tool, sessionID, callID}, output {args}. MCP tools also pass through as _.", "source": "tools/opencode.md §7" }, "hooks.tool-after": { "level": "N", "native": "`tool.execute.after`", "note": "output {title, output, metadata}.", "source": "tools/opencode.md §7" }, "hooks.agent-stop": { "level": "P", "native": "`session.idle` (bus event)", "note": "Closest equivalent; notify-only (verify), per topics/hooks.md.", "source": "tools/opencode.md §7; topics/hooks.md outputs table" }, "hooks.block": { "level": "N", "native": "throw in `tool.execute.before`", "note": "Blocking is by throwing an Error, not exit code or JSON.", "source": "tools/opencode.md §7" }, "hooks.inject-context": { "level": "P", "native": "`experimental.chat.system.transform`, `chat.message`", "note": "Via experimental transform hooks; no `additionalContext` output field.", "source": "tools/opencode.md §7; hub §4 matrix" }, "hooks.rewrite-input": { "level": "N", "native": "mutate `output.args`", "note": "Write to output.args in tool.execute.before.", "source": "tools/opencode.md §7" }, "hooks.rewrite-output": { "level": "N", "native": "mutate `output` in tool.execute.after", "note": "Mutation via output argument; caveats noted in KB.", "source": "tools/opencode.md §7; topics/hooks.md" }, "hooks.model-level": { "level": "P", "native": "`chat.params`, `chat.headers`", "note": "Per-request parameter hooks exist; not a clean before/after model-call pair like Gemini BeforeModel/AfterModel.", "source": "tools/opencode.md §7; hub §4 matrix (P)" }, "hooks.inferential": { "level": "-", "native": "", "note": "No prompt/agent handler type; handlers are plain JS.", "source": "tools/opencode.md §7; hub §4 matrix" }, "hooks.fail-closed": { "level": "P", "native": "throw = block", "note": "No fail-open/closed switch; a thrown error blocks tool hooks, so closed is achievable in code.", "source": "tools/opencode.md §7; topics/hooks.md exit codes table" }, "hooks.cross-read": { "level": "-", "native": "", "note": "Reads .claude skills and CLAUDE.md, not Claude hooks.", "source": "tools/opencode.md ; topics/hooks.md cross-read table" }, "policy.rules": { "level": "N", "native": "`permission` in opencode.json", "note": "allow/ask/deny; last matching rule wins (opposite of Claude); per-agent overrides beat global.", "source": "tools/opencode.md §8; https://opencode.ai/docs/permissions/" }, "policy.repo": { "level": "N", "native": "project `opencode.json`", "note": "Project config merges with global and managed layers.", "source": "tools/opencode.md §2, §8" }, "policy.sandbox": { "level": "-", "native": "", "note": "No OS sandbox documented.", "source": "tools/opencode.md §8" }, "policy.ignore": { "level": "P", "native": "`permission.read` patterns; .gitignore/.ignore", "note": "No deny-read ignore file; .env read denied by default; shell reads and MCP not covered.", "source": "tools/opencode.md §8-9; topics/policy-sandbox-and-ignore.md" }, "policy.managed": { "level": "N", "native": "managed system settings, macOS MDM", "note": "Highest in the config precedence chain; remote .well-known/opencode for org defaults.", "source": "tools/opencode.md §2, §8" }, "mcp.client": { "level": "N", "native": "`mcp` key", "note": "Local and remote servers; `opencode mcp auth|list|logout|debug`.", "source": "tools/opencode.md §10" }, "mcp.project-config": { "level": "N", "native": "opencode.json[c] `mcp`", "note": "Local: type local, command array, environment, timeout (5000 ms, for tool listing). {env:VAR} interpolation.", "source": "tools/opencode.md §10" }, "mcp.remote": { "level": "N", "native": "type: remote (url, headers, oauth)", "note": "OAuth with dynamic client registration (RFC 7591); SSE support unverified.", "source": "tools/opencode.md §10" }, "intel.lsp": { "level": "P", "native": "`lsp` tool (experimental)", "note": "Needs OPENCODE_EXPERIMENTAL_LSP_TOOL=true; 34 built-in servers listed in docs; LSP off by default per docs.", "source": "tools/opencode.md §11" }, "intel.memory": { "level": "-", "native": "", "note": "None documented beyond AGENTS.md and sessions (--continue, --session, --fork).", "source": "tools/opencode.md §13" }, "plugins.package": { "level": "P", "native": "`plugin` array (npm) + .opencode/plugins/", "note": "Code plugins only, not bundles of skills/MCP; hooks are JS.", "source": "tools/opencode.md §12; topics/plugins-and-distribution.md" }, "plugins.marketplace": { "level": "-", "native": "", "note": "No marketplace found; remote .well-known/opencode gives org config.", "source": "tools/opencode.md §12" }, "plugins.agent-plugins": { "level": "-", "native": "", "note": "Not in Agent Plugins compatible-clients list.", "source": "sources/agent-plugins-spec.md" }, "plugins.claude-manifest": { "level": "-", "native": "", "note": "No file looked for; verification log: Gemini CLI, Antigravity, OpenCode get nothing.", "source": "verification log; topics/plugins-and-distribution.md" } } } ], "changelog": [ { "date": "2026-10-18", "kind": "review", "edited": [ "antigravity", "claude-code", "codex", "cursor", "gemini-cli", "github-copilot", "opencode" ], "changes": [ { "type": "level", "host": "antigravity", "hostLabel": "Antigravity", "cap": "hooks.session-start", "capLabel": "Event: session.start", "from": "-", "to": "N" }, { "type": "level", "host": "antigravity", "hostLabel": "Antigravity", "cap": "hooks.rewrite-input", "capLabel": "Hook can rewrite tool input", "from": "?", "to": "N" } ] }, { "date": "2026-10-12", "kind": "review", "edited": [ "antigravity", "claude-code", "codex", "cursor", "gemini-cli", "github-copilot", "opencode" ], "changes": [ { "type": "level", "host": "antigravity", "hostLabel": "Antigravity", "cap": "policy.managed", "capLabel": "Org / enterprise managed policy", "from": "-", "to": "?" }, { "type": "level", "host": "claude-code", "hostLabel": "Claude Code", "cap": "hooks.fail-closed", "capLabel": "Hooks can be configured or default to fail closed", "from": "-", "to": "N" }, { "type": "level", "host": "opencode", "hostLabel": "OpenCode", "cap": "surface.ide", "capLabel": "IDE (editor or extension)", "from": "?", "to": "P" } ] }, { "date": "2026-09-29", "kind": "initial", "hosts": 7, "caps": 47, "changes": [] } ] }