Skip to content

CowboyLogic/ai-dev / skills/client-config-copilotcli

client-config-copilotcli

Unverified

Manage GitHub Copilot CLI configuration files including settings.json, config.json, permissions-config.json, mcp-config.json, lsp-config.json, hooks, skills, custom agents, plugins, and custom instructions. Use this skill whenever the user wants to view, edit, add, or understand any Copilot CLI setting: trusted folders, user or repository settings, tool permissions, sandboxing, MCP or LSP servers, hooks, skills, custom agents, plugins and marketplaces, BYOK models, authentication, session management, or custom instructions. Trigger on: "add trusted folder", "allow tool", "configure MCP", "add hook", "create skill", "create agent", "install plugin", "set model", "use my own API key", "add custom instructions", "name session", "resume session", or "show my copilot config".

FileKindSize
CHANGELOG.mdmarkdown19.4 KB
README.mdmarkdown2.3 KB
SKILL.mdskill md7.6 KB
references/agents-plugins.mdmarkdown11.5 KB
references/cli-commands.mdmarkdown15.2 KB
references/config-schema.mdmarkdown37.2 KB
references/hooks.mdmarkdown15.6 KB
references/instructions.mdmarkdown4.1 KB
references/mcp.mdmarkdown12.1 KB
references/permissions.mdmarkdown22.8 KB
references/skills.mdmarkdown5.8 KB
scripts/show-config.pyscript14.5 KB
scripts/update-references.pyscript5.6 KB
sources.jsonconfig12.2 KB

references/hooks.md

View on GitHub
# Hooks Reference

Hooks run external commands (or HTTP calls, or auto-submitted prompts) at lifecycle points in a
session. Copilot CLI and Copilot cloud agent share the format; differences are noted.

## Where hooks are loaded from (CLI)

All sources are combined; when the same event appears in several, every entry runs. Load order:

| Source | Location |
|--------|----------|
| Policy (admin, machine-wide) | `/etc/github-copilot/policy.d/*.json` (Linux/macOS), `C:\ProgramData\GitHub\Copilot\policy.d\*.json` or registry `HKLM\Software\Policies\GitHub\Copilot` (Windows) |
| Repository hook files | `.github/hooks/*.json` — any number of files, name each after its purpose |
| User hook files | `~/.copilot/hooks/*.json` (`$COPILOT_HOME/hooks/` if set; Windows `%USERPROFILE%\.copilot\hooks\`) |
| Repository inline | `hooks` key in `.github/copilot/settings.json` or `.github/copilot/settings.local.json` (also `.claude/settings.json` / `.claude/settings.local.json`) |
| User inline | `hooks` key in `~/.copilot/settings.json` (`~/.copilot/config.json` is no longer read for hooks) |
| Plugins | Each plugin's `hooks.json` or `hooks/hooks.json` |

- Hook config changes load when the CLI starts — restart after editing.
- Policy hooks must be root-owned and not group/world-writable (POSIX); they ignore
  `disableAllHooks` and folder trust.
- Repository hooks in prompt mode (`-p`) load only if the folder is trusted, `COPILOT_ALLOW_ALL` is
  set, or `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=true`.
- Cloud agent reads only `.github/hooks/*.json` from the cloned repo (must be on the default
  branch), runs on Linux, honors only `bash` (or `command`) entries, and has a firewall-restricted
  network: by default only GitHub and Copilot hostnames are reachable, so another host (such as a
  webhook endpoint) needs an admin-configured firewall allow rule. The job is non-interactive with
  all tool permissions pre-granted. Its filesystem is ephemeral, so send hook output elsewhere from a
  `bash` hook (for example with `curl` to an allowed host). The working directory is `/workspace` when a repository is cloned (otherwise
  `/root`) and `HOME` is `/root`. `GITHUB_COPILOT_API_TOKEN`, `GITHUB_COPILOT_GIT_TOKEN`, and
  `COPILOT_AGENT_PROMPT` (the prompt the job was invoked with) are set; `GITHUB_TOKEN` is not.
- Windows: the docs' example hooks need PowerShell 7+ (`pwsh`) — `winget install Microsoft.PowerShell`.
- **v1.0.97 release notes only:** after `--resume`, hooks from repository-local marketplace
  plugins keep running, and hooks from plugins your configuration disabled no longer come back.

### Agent-scoped hooks (CLI only)

A custom agent's frontmatter can carry a `hooks` event map. The hooks run only while that agent is
selected, in addition to session, user, repository, plugin, and policy hooks. Added in v1.0.97
(release notes); documented in the hooks reference.

```yaml
---
name: formatter
description: Formats changed files
hooks:
  PostToolUse:
    - type: command
      command: ./scripts/format-changed-files.sh
      windows: ./scripts/format-changed-files.ps1
---
Format the files you change.
```

| Behavior | Details |
|----------|---------|
| Event names | Runtime names such as `postToolUse` and aliases such as `PostToolUse` are accepted |
| Commands | `command` is the fallback; `windows`, `linux`, and `osx` override it per platform; paths resolve from the repository root |
| Subagent `Stop` | A subagent's scoped `Stop` (`agentStop`) hooks run at `SubagentStop`; after eight consecutive scoped blocks, further blocks are ignored |
| Trust | Repository and inherited-agent hooks require workspace admission; hook-disable settings, enterprise restrictions, and timeouts still apply |
| Unsupported | Remote or organization-hosted agent definitions don't run scoped hooks |

The hooks reference scopes this feature to Copilot CLI. It's the `hooks` frontmatter field of a
custom agent, not a field of the hook files above (see `agents-plugins.md`).

## File structure

```json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/validate-tool.sh",
        "powershell": "./scripts/validate-tool.ps1",
        "cwd": ".",
        "timeoutSec": 30,
        "env": { "LOG_LEVEL": "INFO" },
        "matcher": "bash|edit"
      }
    ]
  }
}
```

- `"version": 1` is required.
- A malformed item in a hook **file** is dropped and logged; siblings still load. Invalid JSON, a
  bad `version`, or a non-array event list rejects the whole file. Inline `hooks` in
  `settings.json` are strict — any item error rejects the whole field.
- Optional top-level `"disableAllHooks": true` skips every hook in that file.

---

## Hook entry types

### `command`

| Field | Required | Description |
|-------|----------|-------------|
| `type` | No | `"command"` (default when omitted) |
| `bash` | One of `bash`/`powershell`/`command` (unless `exec`) | Unix shell command |
| `powershell` | One of `bash`/`powershell`/`command` (unless `exec`) | Windows shell command |
| `command` | One of `bash`/`powershell`/`command` (unless `exec`) | Cross-platform fallback, copied to whichever of `bash`/`powershell` is absent |
| `exec` | Instead of the shell fields | Executable run directly, no shell (CLI only) |
| `args` | No | Arguments for `exec` (CLI only) |
| `cwd` | No | Working directory (relative to repo root, or absolute) |
| `env` | No | Extra environment variables (supports variable expansion) |
| `timeoutSec` | No | Seconds; default `30` |
| `timeout` | No | Alias for `timeoutSec` (used only if `timeoutSec` is absent) |
| `matcher` | No | Regex filter (see [Matchers](#matchers)) |

Don't combine `exec` with `bash`/`powershell`/`command`.

**Input** arrives as JSON on **stdin**. **Output** is JSON on stdout — exactly one final object.
Progress lines are allowed before it: a single-line `{"type": "progress", "message": "...",
"temporary": true}` is shown in the timeline and stripped from the output. Output over 10 MiB is
truncated; unparseable output is treated as no output.

### `http`

Posts the input payload as JSON.

| Field | Required | Description |
|-------|----------|-------------|
| `type` | Yes | `"http"` |
| `url` | Yes | `https://` required for `preToolUse` and `permissionRequest`. Plain `http://` only for localhost with `COPILOT_HOOK_ALLOW_LOCALHOST=1` |
| `headers` | No | Request headers |
| `allowedEnvVars` | No | Env var names that may be expanded inside `headers` (forces `https://`) |
| `timeoutSec` / `timeout` | No | Seconds; default `30` |

```json
{
  "type": "http",
  "url": "https://hooks.example.com/copilot",
  "headers": { "X-Source": "copilot-cli" },
  "timeoutSec": 10
}
```

The docs don't show the placeholder syntax for expanding `allowedEnvVars` inside `headers`;
verify before relying on it.

### `prompt` (CLI, `sessionStart` only)

Auto-submits text or a slash command at the start of a **new interactive** session (not on resume,
not in `-p`).

```json
{ "type": "prompt", "prompt": "/chronicle standup" }
```

---

## Hook events

| Event | Fires when | Output used |
|-------|------------|-------------|
| `sessionStart` | New or resumed session begins | Optional `additionalContext` |
| `sessionEnd` | Session ends (also `/clear`, with `reason: "user_exit"`) | No |
| `userPromptSubmitted` | User submits a prompt | `modifiedPrompt` — SDK hooks only; config-file hook output is dropped |
| `userPromptTransformed` | Prompt transformed into model-facing content | `modifiedTransformedPrompt` |
| `preToolUse` | Before each tool runs | Allow / deny / ask / modify args |
| `permissionRequest` | Before the permission service runs (CLI only) | `behavior` allow/deny |
| `postToolUse` | After a tool succeeds | `modifiedResult`, `additionalContext` |
| `postToolUseFailure` | After a tool fails | `additionalContext` (exit `2`) |
| `agentStop` | Main agent finishes a turn | `decision: "block"` forces another turn |
| `subagentStart` | Subagent spawned | `additionalContext` prepended to its prompt |
| `subagentStop` | Subagent completes | `decision`, `reason`, `modifiedResponse` |
| `preCompact` | Context compaction begins | No |
| `errorOccurred` | An error occurs | No |
| `notification` | CLI system notification (async, CLI only) | Optional `additionalContext` |

Event-name casing selects the payload format: camelCase (`preToolUse`) gets camelCase fields;
PascalCase VS Code-compatible names (`SessionStart`, `SessionEnd`, `UserPromptSubmit`,
`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStop`, `ErrorOccurred`,
`PreCompact`, `PermissionRequest`) get snake_case fields (`tool_name`, `tool_input`,
`hook_event_name`, ...).

The built-in `general-purpose` agent does not emit `subagentStart`/`subagentStop`.

### Input payloads (camelCase)

Every payload includes `sessionId`, `timestamp` (epoch ms), and `cwd`. Additional fields:

| Event | Extra fields |
|-------|--------------|
| `sessionStart` | `source` (`"startup"`, `"resume"`, `"new"`), `initialPrompt?` |
| `sessionEnd` | `reason` (`"complete"`, `"error"`, `"abort"`, `"timeout"`, `"user_exit"`) |
| `userPromptSubmitted` | `prompt` |
| `userPromptTransformed` | `prompt`, `transformedPrompt` |
| `preToolUse` | `toolName`, `toolArgs` |
| `postToolUse` | `toolName`, `toolArgs`, `toolResult { resultType, textResultForLlm }` |
| `postToolUseFailure` | `toolName`, `toolArgs`, `error` |
| `agentStop` | `transcriptPath`, `stopReason`, `stop_hook_active` |
| `subagentStart` | `transcriptPath`, `agentName`, `agentDisplayName?`, `agentDescription?` |
| `subagentStop` | `transcriptPath`, `agentId`, `agentType`, `agentName`, `agentDisplayName?`, `response`, `stopReason` |
| `errorOccurred` | `error { message, name, stack? }`, `errorContext`, `recoverable` |
| `preCompact` | `transcriptPath`, `trigger` (`"manual"`/`"auto"`), `customInstructions` |
| `notification` | `hook_event_name`, `message`, `title?`, `notification_type` |

Hooks that fire inside a subagent also receive `agentId`, `agentType` (when known), and
`parentAgentId` (when known); snake_case payloads use `agent_id`, `agent_type`, and
`parent_agent_id`. Root-agent hook inputs are unchanged.

`notification_type` values: `shell_completed`, `shell_detached_completed`, `agent_completed`,
`agent_idle`, `permission_prompt`, `elicitation_dialog`.

---

## Decision output

### `preToolUse`

| Field | Values |
|-------|--------|
| `permissionDecision` | `"allow"`, `"deny"`, `"ask"` (cloud agent treats `"ask"` as deny; in CLI autopilot mode no prompt is shown and `"ask"` is denied, so the agent sees the CLI couldn't ask the user) |
| `permissionDecisionReason` | Required when denying; shown to the agent |
| `modifiedArgs` | Replacement tool arguments |

If any `preToolUse` hook denies, the tool is blocked.

### `permissionRequest`

| Field | Values |
|-------|--------|
| `behavior` | `"allow"`, `"deny"` — short-circuits the normal permission flow |
| `message` | Reason fed back when denying |
| `interrupt` | `true` with deny stops the agent |

Doesn't run for `read` and `hook` permission kinds. A hook `allow` never pre-approves a
sandbox-bypass request (only `deny` propagates). Useful for `-p`/CI where no prompt is possible.

### `postToolUse`

`modifiedResult` (`{ resultType: "success", textResultForLlm }`) replaces the result;
`additionalContext` is appended to the tool output (joined across hooks, capped at 10 KB).

### `agentStop` / `subagentStop`

`decision: "block"` plus `reason` forces another turn using `reason` as the prompt.
`subagentStop` also accepts `modifiedResponse`. After 8 consecutive blocks the CLI ends the turn
anyway — check `stop_hook_active` to self-limit.

---

## Matchers

`matcher` is a regex anchored as `^(?:PATTERN)$` — it must match the full value. Invalid regexes
skip the entry.

| Event | Matched against |
|-------|-----------------|
| `preToolUse`, `postToolUse`, `permissionRequest` | `toolName` |
| `subagentStart` | `agentName` |
| `preCompact` | `trigger` |
| `notification` | `notification_type` |

Tool names: `ask_user`, `bash`, `create`, `edit`, `glob`, `grep`, `powershell`, `task`, `view`,
`web_fetch`.

PascalCase `PreToolUse` / `PermissionRequest` use Claude-style matchers: `*`, `**`, or empty
matches everything; `Bash` or `Edit|Write` match Claude tool names (`bash`/`powershell` → `Bash`,
`view` → `Read`, `create` → `Write`, `edit`/`apply_patch` → `Edit`, `grep` → `Grep`, `glob` →
`Glob`, `web_fetch` → `WebFetch`, `web_search` → `WebSearch`, `ask_user` → `AskUserQuestion`,
`update_todo` → `TodoWrite`, `task` → `Agent`, `str_replace_editor` → `Edit`, `rg` → `Grep`). Any
other regex is case-sensitive and anchored (`^(?:PATTERN)$`) against the Claude tool name, or the
runtime name when a tool has no Claude equivalent. Tools with no Claude equivalent keep their
runtime names.

---

## Exit codes and failure behavior

| Exit | Meaning |
|------|---------|
| `0` | Success; stdout parsed as output |
| `2` | Warning (stderr shown). **Deny** for `preToolUse` and `permissionRequest`. For `postToolUseFailure`, stdout becomes `additionalContext` |
| Other non-zero | Logged, run continues — **except** `preToolUse` command hooks, which deny |
| Timeout | Always fail-open, even for `preToolUse` and policy hooks |

HTTP `preToolUse` hooks are fail-open on network errors, timeouts, and non-2xx responses.

---

## Sandboxed sessions

When the session sandbox is enabled, command hooks from the repository, user settings, and plugins
run inside it with the same access as the agent's shell commands. A hook can also read the
directory it was loaded from, and a plugin hook can write to `$COPILOT_PLUGIN_DATA`.

- A hook's `cwd` and `env` don't widen access: a `cwd` outside the session's grants gives the hook
  no access there, and `TMPDIR`/`PATH` set in `env` grant nothing.
- A hook that fails in the sandbox shows a warning once per hook and session. To give it more
  access, add paths to `sandbox.userPolicy` in your settings (see `permissions.md`).
- Policy hooks always run on the host, outside the sandbox — a policy hook shouldn't run scripts
  from the workspace.

---

## Disabling hooks

- `"disableAllHooks": true` inside a hook file skips that file's hooks.
- `disableAllHooks: true` in repository or user `settings.json` skips every hook from every source
  for those sessions (CLI only); policy hooks still run.

---

## Examples

### Block destructive shell commands (`.github/hooks/guard.json`)

```json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "matcher": "bash",
        "bash": "./.github/hooks/block-dangerous.sh",
        "timeoutSec": 10
      }
    ]
  }
}
```

```bash
#!/bin/bash
# block-dangerous.sh — input JSON arrives on stdin
INPUT=$(cat)
if echo "$INPUT" | grep -qE 'rm -rf|DROP TABLE'; then
  echo '{"permissionDecision": "deny", "permissionDecisionReason": "Destructive command blocked by hook"}'
fi
exit 0
```

### Notify when the agent stops (macOS, `~/.copilot/hooks/notify.json`)

```json
{
  "version": 1,
  "hooks": {
    "agentStop": [
      {
        "type": "command",
        "bash": "osascript -e 'display notification \"Agent stopped\" with title \"Copilot CLI\"'",
        "timeoutSec": 5
      }
    ]
  }
}
```

---

## Testing and debugging

```bash
# Pipe sample input into the script
echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' \
  | ./.github/hooks/block-dangerous.sh

echo $?                                   # exit code
./.github/hooks/block-dangerous.sh < sample.json | jq .   # validate output JSON
```

Checklist when hooks don't run: file in the right directory, valid JSON (`jq . file.json`),
`"version": 1` present, script executable (`chmod +x`) with a shebang, output is one JSON object,
CLI restarted. Add `set -x` and write debug output to stderr.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall