GitHub Copilot CLI: full reference

This page comes from agentltl-copilot-cli/docs/REFERENCE.md

It is kept with the code it documents. Edit it there.

The plugin is the Claude Code plugin's guard on Copilot CLI's hooks. Both are thin layers over agentltl-coding, which holds the rule language, the library, the guard and what the hooks do; each plugin only translates its agent's payloads, tool names and files.

Setup

copilot plugin marketplace add AgentLTL/agentltl-copilot-cli
copilot plugin install agentltl@agentltl

• The first hook builds a Python environment in the plugin's data directory (~/.copilot/plugin-data/agentltl/venv-<pins>), from the commits pinned in vendor.lock. It needs Python 3.10+ and git. A plugin update that changes the pins builds a new one; environments unused for 14 days are removed.
• Rules apply where an AGENTLTL.yaml is: the project's (found from the working directory up to the git root) and the user's, ~/.copilot/AGENTLTL.yaml ($COPILOT_HOME if set). Without either, the hooks exit at once.
• bin/agentltl is the command line. Copilot CLI does not put a plugin's bin/ on the PATH: agentltl install-cli links it into ~/.local/bin, and the skills find it in the plugin folder otherwise.

Claude Code plugin features, in Copilot CLI

Claude Code plugin	Copilot CLI plugin
.claude-plugin/plugin.json, marketplace.json	plugin.json at the root, .github/plugin/marketplace.json
claude plugin install agentltl@agentltl	copilot plugin install agentltl@agentltl
Hooks: SessionStart, PreToolUse, UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop	sessionStart, preToolUse, userPromptSubmitted, postToolUse, postToolUseFailure, agentStop (hooks.json, version 1)
${CLAUDE_PLUGIN_ROOT} in hook commands	PLUGIN_ROOT (also COPILOT_PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT); hooks run with the plugin folder as their working directory, the project is in the payload's cwd
${CLAUDE_PLUGIN_DATA}	COPILOT_PLUGIN_DATA, given to hooks only; hooks/run notes it in the plugin folder (.data-dir) so agentltl run by hand uses the same environment and state
PreToolUse permissionDecision deny / ask, with a reason	the same fields, at the top level of the answer
PreToolUse additionalContext (a note on a call that goes ahead)	no such field: the note is kept and given with the call's result, in postToolUse
systemMessage when a stop rule fires	no such field: the deny reason says the session is stopped
PostToolUse exit status: PostToolUseFailure is status 1	a shell command that exits non-zero still reports resultType: success: its status is read from the <shellId: … completed with exit code N> line of the output; postToolUseFailure is status 1
Stop decision: block for finally rules	agentStop decision: block. Copilot sends the reason back as a new prompt (a userPromptSubmitted); the plugin recognises it, so it doesn't count as the user replying and finish_retries still bounds the loop
permission_mode (auto modes)	not in the payload. In copilot -p an ask is refused, even with --allow-all-tools; AGENTLTL_AUTO=1 marks an unattended run for unparseable.auto
CLAUDE_PROJECT_DIR	COPILOT_PROJECT_DIR, else the git root of the working directory
(no Claude Code equivalent)	the skill tool call that loads a skill; recorded under its own name
Tools Bash, Write, Edit, Read, Glob, Grep, Task, WebFetch	bash, create, edit, view, glob, grep, task, web_fetch, mapped onto those names and their arguments, so rules and the library are the same
~/.claude/AGENTLTL.yaml	~/.copilot/AGENTLTL.yaml
Memory: CLAUDE.md, .claude/rules/, auto memory	Custom instructions: .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, AGENTS.md (also CLAUDE.md, GEMINI.md), ~/.copilot/copilot-instructions.md, ~/.copilot/instructions/
Built-in rule memory-first	the same, on Copilot's instruction files
Skills /agentltl:setup, :rules, :import, :status	/agentltl-setup, /agentltl-rules, /agentltl-import, /agentltl-status
agentltl on Claude's PATH	agentltl install-cli
Status line (~/.claude/settings.json)	statusLine in ~/.copilot/settings.json plus the STATUS_LINE feature flag (experimental in Copilot CLI)
Library no-claude-coauthor, subagents-on-sonnet	no-copilot-coauthor; the Claude Code entries switch nothing on here

Hooks

Event	Input used	Answer
sessionStart	cwd	additionalContext: the rules in force, one line each (settings.announce), or the problems of a broken rule file
preToolUse	sessionId, cwd, toolName, toolArgs (an object, or a JSON string)	permissionDecision deny or ask and permissionDecisionReason; nothing when there is no objection
postToolUse	toolResult.resultType, toolResult.textResultForLlm (and its exit code line)	additionalContext: a note the rules left on the call, a credential warning
postToolUseFailure	error	the same
userPromptSubmitted	prompt	lifts a stop; finally rules may send Copilot back again (not when the prompt is the plugin's own agentStop reason coming back)
agentStop	stop_hook_active	decision: block with what a finally rule still needs

The guard never answers allow: silence leaves the call to Copilot's own permissions. An internal error in preToolUse answers ask, and a non-zero exit would deny the call, so a broken guard is never silently open. Copilot lets a hook that times out through.

Modes

Mode	In Copilot CLI
block	denied with the reason
warn	denied once; Copilot may repeat the exact same call to go ahead
ask	Copilot asks you to approve the call
retry	denied; after retries attempts, you are asked
stop	denied, and every call is denied until you write again
log	allowed; Copilot gets the note with the call's result

Rules

The rule language is the same in every harness: see the rules reference and the library. In agentltl check, a step may name Copilot's own tools: 'create {"path": ".env", "file_text": "x"}'.

State

Session and project traces live in the plugin's data directory (sessions/, projects/), as in the Claude Code plugin: agentltl trace shows them, agentltl reset forgets them.

Development

git clone --recurse-submodules https://github.com/AgentLTL/agentltl-copilot-cli.git
scripts/setup.sh --dev && .venv/bin/pytest -q

tests/fixtures/payloads/ holds a session captured from Copilot CLI 1.0.92; the tests replay it. docker/Dockerfile is an image with Copilot CLI to try the plugin end to end.