skilldrop-cli 0.16.34 → 0.16.36

package/packs/ai-engineering/skills/agent-config-review/reference.md

@@ -0,0 +1,205 @@
+# agent-config-review — reference
+
+## Where each tool keeps its configuration
+
+| Tool | File | Scope | Holds |
+|---|---|---|---|
+| Claude Code | managed-settings.json in the system folder (macOS `/Library/Application Support/ClaudeCode/`, Linux and WSL `/etc/claude-code/`), or pushed by an admin | managed | anything below; outranks every other scope |
+| Claude Code | `~/.claude/settings.json` | user | every project on the machine |
+| Claude Code | `.claude/settings.json` | project | committed, shared with everyone who clones |
+| Claude Code | `.claude/settings.local.json` | local | per-person; should be git-ignored |
+| Claude Code | `.mcp.json` | project | MCP servers, committed |
+| Claude Code | `~/.claude.json` | user and local | MCP servers added with `claude mcp add` (local scope sits under `projects.<path>.mcpServers`) |
+| Claude Code | `.claude/agents/*.md`, `~/.claude/agents/*.md` | project, user | subagents: `tools:`, `permissionMode:`, `model:` |
+| Claude Code | enabled plugins | any | can add hooks, MCP servers, subagents and commands not visible in the files above |
+| Codex | `~/.codex/config.toml`, and a project `.codex/config.toml` if present | user, project | `approval_policy`, `sandbox_mode`, `[sandbox_workspace_write]`, `[shell_environment_policy]`, `[profiles.*]`, `[mcp_servers.*]` |
+| Cursor | `.cursor/mcp.json`, `~/.cursor/mcp.json` | project, user | MCP servers |
+| Cursor | `.cursor/rules/*.mdc`, `.cursorrules` | project | instructions the agent follows on every request |
+| Cursor | `.cursor/cli.json`, `~/.cursor/cli-config.json` | project, user | CLI agent permissions (`Shell(...)`, `Read(...)`, `Write(...)` allow and deny) |
+| Cursor | app settings (auto-run, command allowlist) | user | not in the repo; ask for a screenshot or treat as unknown |
+| VS Code / Copilot | `.vscode/settings.json`, user settings | project, user | `chat.tools.autoApprove` / `chat.tools.global.autoApprove`, `chat.tools.terminal.autoApprove` |
+| VS Code / Copilot | `.vscode/mcp.json` | project | MCP servers under `servers`, secrets via `inputs` |
+| Any | `package.json`, `Makefile`, shell scripts, CI workflows, devcontainer | project | launch flags: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, Codex `--dangerously-bypass-approvals-and-sandbox` / `--yolo`, `--full-auto` |
+
+## How the scopes combine
+
+**Claude Code.** Precedence for a single value, high to low: managed > command-line flags >
+local > project > user. Lists (`permissions.allow`, `ask`, `deny`, `additionalDirectories`,
+sandbox domain lists) are combined across scopes, not replaced. Rules are evaluated deny first,
+then ask, then allow, so a deny in any scope beats an allow in any scope. Hooks from every scope
+run. Managed policy can narrow all of this: `allowManagedPermissionRulesOnly` (only managed
+rules count), `allowManagedHooksOnly` (only managed hooks run), and
+`permissions.disableBypassPermissionsMode: "disable"` (bypass mode can't be turned on).
+Project settings take effect once the user trusts the folder.
+
+**Codex.** Command-line flags (`-c key=value`, `--sandbox`, `--ask-for-approval`) > the profile
+named by `--profile` or the top-level `profile` key > top-level keys. A profile that sets
+`sandbox_mode` replaces the top-level value for every session launched with it.
+
+**Cursor and VS Code.** User settings apply everywhere; workspace settings override them for the
+folder. An MCP server defined in both a project and a user file runs from whichever the tool
+loads for that name; list both.
+
+## What a wildcard allow entry really permits
+
+`Bash(x:*)`, `Bash(x *)` and `Bash(x*)` all mean "any command starting with `x`, any arguments".
+
+| Entry | What it lets run without asking |
+|---|---|
+| `Bash`, `Bash(*)` | any shell command |
+| `Bash(python3:*)`, `node`, `ruby`, `perl`, `php`, `deno`, `bun` | any code (`-c`, `-e`) |
+| `Bash(bash:*)`, `sh`, `zsh`, `pwsh` | any shell |
+| `Bash(npm:*)`, `pnpm`, `yarn` | any `package.json` script; `npm exec` / `dlx` download and run any package |
+| `Bash(npx:*)`, `bunx`, `uvx`, `pipx` | download and run any package |
+| `Bash(pip:*)`, `uv` | package installs whose setup code runs; `uv run` runs anything |
+| `Bash(make:*)`, `just`, `cargo`, `go` | whatever the build file says; `go run`, `cargo run`, build scripts |
+| `Bash(docker:*)`, `docker compose`, `podman` | containers that mount the host disk (`-v /:/host`) or run privileged |
+| `Bash(kubectl:*)` | anything the kubeconfig's cluster role allows |
+| `Bash(git:*)` | `git -c core.sshCommand=…`, aliases and repo hooks run commands; `git push` sends code to any remote |
+| `Bash(gh:*)` | `gh api` calls anything the token allows, deletes included |
+| `Bash(curl:*)`, `wget` | uploads any file to any host; downloads code |
+| `Bash(ssh:*)`, `scp`, `rsync` | commands on other machines; copies data off this one |
+| `Bash(find:*)`, `xargs`, `env`, `sudo`, `timeout`, `nohup`, `watch` | whatever command follows (`find -exec`, `xargs sh`) |
+| `Bash(awk:*)`, `sed` | commands via `system()` or GNU sed's `e` |
+| `Edit`, `Write` with no path | any file, the agent's own settings, hooks and CI files included |
+| `WebFetch` with no domain | any URL; the query string carries data out |
+| `mcp__server` or `mcp__server__*` | every tool on that server, writes included |
+
+Exact entries are safe to allow: `Bash(npm run test)`, `Bash(npm run lint)`, `Bash(git status)`,
+`Bash(git diff:*)`, `Bash(git log:*)`, `WebFetch(domain:docs.example.com)`,
+`mcp__github__get_pull_request`. Use only command and script names the input shows.
+
+## Settings that run shell without asking
+
+- `hooks` — every event: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`, `SessionEnd`. A hook gets the tool input on stdin and runs with the user's full access, outside the sandbox.
+- `statusLine` (`type: command`) — runs repeatedly while the session is open.
+- `apiKeyHelper`, `awsAuthRefresh`, `awsCredentialExport`, `otelHeadersHelper` — run to fetch credentials.
+- MCP servers with a `command` — start when the session does, outside the sandbox.
+- Codex `[mcp_servers.*]` and Cursor `.cursor/mcp.json` servers — same.
+
+Downloaded-and-run is the critical shape: a fetch (`curl`, `wget`, `Invoke-WebRequest`, a URL)
+piped into an interpreter, or saved and then executed. Whoever can change the remote file runs
+code on every machine, every session.
+
+## Sandbox keys (Claude Code)
+
+| Key | Strict value | Wrong value means |
+|---|---|---|
+| `sandbox.enabled` | `true` | shell commands run with the user's full access |
+| `sandbox.allowUnsandboxedCommands` | `false` | a command that fails in the sandbox retries outside it |
+| `sandbox.excludedCommands` | `[]` | those commands always run outside |
+| `sandbox.network.allowedDomains` | the hosts the work needs | wildcards and open-publish hosts (`*.githubusercontent.com`, gist and paste sites, tunnels) are a payload source and a drop box |
+| `sandbox.autoAllowBashIfSandboxed` | either, if strict | when on, sandboxed commands run without a prompt, so the sandbox is the only control |
+| `sandbox.failIfUnavailable` | `true` where policy requires it | the session starts unsandboxed when the OS sandbox is missing |
+
+Codex equivalents: `sandbox_mode = "workspace-write"` (not `danger-full-access`),
+`[sandbox_workspace_write] network_access = false`, `approval_policy = "on-request"` or
+`"untrusted"` (not `"never"` outside a disposable container).
+
+## Replacement snippets
+
+**Claude Code project settings, tightened** — exact commands, deny kept, strict sandbox:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(npm run test)", "Bash(npm run lint)", "Bash(git status)", "Bash(git diff:*)"],
+    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "WebFetch"]
+  },
+  "sandbox": {
+    "enabled": true,
+    "allowUnsandboxedCommands": false,
+    "network": { "allowedDomains": ["registry.npmjs.org"] }
+  },
+  "enableAllProjectMcpServers": false
+}
+```
+
+**A hook that ran a downloaded script** — commit the script, review it, run the local copy:
+
+```json
+"hooks": {
+  "SessionStart": [
+    { "hooks": [ { "type": "command", "command": "bash ./tools/agent-bootstrap.sh" } ] }
+  ]
+}
+```
+
+**`.mcp.json` with no secret and a pinned package:**
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "<package>@<exact-reviewed-version>"],
+      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
+    }
+  }
+}
+```
+
+**A subagent with only what its job needs:**
+
+```markdown
+---
+name: db-migrator
+description: Writes database migrations. Use when a change needs a schema migration.
+tools: Read, Grep, Glob, Edit, Bash
+---
+```
+
+`Bash` in a subagent's list is still held by the session's permission rules and sandbox, so
+the allow list decides which commands it runs without asking. Leave `Bash` out of a subagent
+that only reads.
+
+**Codex profile that keeps a person and the sandbox:**
+
+```toml
+[profiles.fast]
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[shell_environment_policy]
+inherit = "core"
+```
+
+**VS Code** — turn off global auto-approve and approve terminal commands exactly:
+
+```json
+{
+  "chat.tools.autoApprove": false,
+  "chat.tools.global.autoApprove": false,
+  "chat.tools.terminal.autoApprove": { "npm run test": true, "npm run lint": true }
+}
+```
+
+**Managed policy lines** an organisation can set so no project can loosen them:
+
+```json
+{
+  "permissions": { "disableBypassPermissionsMode": "disable" },
+  "allowManagedHooksOnly": true
+}
+```
+
+**Keep personal files out of git:**
+
+```gitignore
+.claude/settings.local.json
+.env
+.env.*
+```
+
+If the file is already tracked, an ignore line does nothing until it is untracked:
+
+```bash
+git rm --cached .claude/settings.local.json
+```
+
+## A secret in a committed file
+
+1. Rotate it at the issuer (revoke the old value, issue a new one with the narrowest scope the work needs).
+2. Replace the literal with a reference: `${VAR}` in Claude Code `.mcp.json` and settings `env`, `${env:VAR}` in Cursor, an `inputs` prompt in `.vscode/mcp.json`, the shell environment the server inherits in Codex.
+3. Treat the history as exposed: removing the line or rewriting history does not un-leak a value that was pushed or cloned.
+4. What can't be told from the files: whether it was pushed, whether the repo is public, what scopes the token has. Each goes under "To confirm".