[copilot-cli-research] Copilot CLI Deep Research - 2026-02-19

[github-actions[bot]]

Analysis Date: 2026-02-19 | Repository: github/gh-aw | Scope: 80 Copilot workflows out of 154 total (51.9%) | Copilot CLI Version: 0.0.411

---

📊 Executive Summary

Research Topic: Copilot CLI Optimization Opportunities in github/gh-aw
Key Findings:

1. engine.env, plugins, and tools-timeout are available but completely unused (0%)
2. engine.agent (custom agent files) used in only 4 workflows (5%) despite 10 agent files existing in .github/agents/
3. AWF sandbox firewall adopted in only 15 workflows (18.8%) despite workflows actively fetching external web resources
4. safe-inputs at 6.3% while many workflows could safely delegate complex CLI operations
5. tools.agentic-workflows tool used in only 3 workflows despite significant meta-orchestration potential

The repository shows a mature, security-conscious architecture with strong adoption of safe-outputs (100%), github tool (93.8%), timeout-minutes (95%), and cache-memory (83.8%). The most impactful gaps are around AWF sandbox adoption, custom agent files, and the unused engine.env configuration.

---

🔴 Critical Findings

High Priority Issues

1. AWF Sandbox Underadoption
15 of 80 workflows (18.8%) use the AWF firewall sandbox, but ~13 workflows actively use web-fetch: or external network access without sandbox protection. Security exposure for workflows fetching external content.

2. engine.env Completely Unused
The engine.env field (0% adoption) allows injecting custom environment variables into the Copilot CLI process. Many workflows pass configuration through hardcoded values in prompts or bash steps when they could use typed env vars.

3. engine.agent Custom Files Not Connected
10 custom agent files exist in .github/agents/ (e.g., technical-doc-writer.agent.md, contribution-checker.agent.md, ci-cleaner.agent.md) but only 4 workflows actually reference them via engine.agent:. Most specialized workflows craft entire agent personas in their prompt body instead.

Medium Priority Opportunities

4. safe-inputs Underused
Only 5 workflows (6.3%) use safe-inputs for controlled command execution. Several workflows use bash: ["*"] (unrestricted wildcard) or run gh api calls directly when they could benefit from safe-inputs for auditable, scoped operations.

5. tools-timeout / startup-timeout Absent
tools-timeout and startup-timeout are available for controlling MCP server behavior but used in 0 workflows. Workflows with complex MCP tool chains (serena + playwright + github) could benefit from explicit timeouts to prevent hangs.

---

1️⃣ Current State Analysis

View Copilot CLI Capabilities Inventory

Available CLI Features

Category	Feature	Status
Engine Config	engine.model	Available
Engine Config	engine.args	Available
Engine Config	engine.agent	Available (references .github/agents/*.agent.md)
Engine Config	engine.env	Available
Engine Config	engine.command	Available
Engine Config	engine.version	Available
Engine Config	engine.max-turns	Not yet supported (supportsMaxTurns: false)
Sandbox	sandbox.agent: awf	Available (AWF v0.15.0+ chroot mode)
Sandbox	sandbox.agent: srt	Available (alternative to AWF)
Sandbox	sandbox.mcp	Available (MCP gateway container)
Network	network.allowed	Available with protocol prefixes
Tools	tools.github	Available (with toolsets, granular permissions)
Tools	tools.playwright	Available
Tools	tools.web-fetch	Available (builtin)
Tools	tools.bash	Available (wildcard or specific commands)
Tools	tools.edit	Available
Tools	tools.serena	Available
Tools	tools.agentic-workflows	Available
Tools	tools.cache-memory	Available
Tools	tools-timeout	Available
Tools	tools.startup-timeout	Available
Safety	safe-outputs	Available (many types)
Safety	safe-inputs	Available
Plugins	plugins (experimental)	Available
Model	GH_AW_MODEL_AGENT_COPILOT org var	Available (org-level default)
CLI Flags	--share	Always enabled (auto-added)
CLI Flags	--disable-builtin-mcps	Always enabled (auto-added)
CLI Flags	--add-dir	Auto-added for configured paths
CLI Flags	--allow-all-paths	Auto-added when edit tool used

View Usage Statistics

Usage Statistics (80 Copilot Workflows)

Feature	Count	%	Trend
safe-outputs	80	100%	✅ Universal
timeout-minutes	76	95%	✅ Near-universal
github tool	75	93.8%	✅ Near-universal
network: config	71	88.8%	✅ Wide adoption
cache-memory	67	83.8%	✅ Wide adoption
serena tool	22	27.5%	📈 Growing
imports	35	43.75%	📈 Growing
sandbox: config	19	23.8%	⚠️ Moderate
engine.args	14	17.5%	⚠️ Occasional
web-fetch tool	13	16.3%	⚠️ Occasional
playwright tool	11	13.8%	⚠️ Occasional
engine.model	9	11.3%	⚠️ Rare
safe-inputs	5	6.3%	🔴 Rare
engine.max-turns	5	6.3%	🔴 Rare
engine.agent	4	5.0%	🔴 Very rare
engine.version	3	3.8%	🔴 Very rare
agentic-workflows	3	3.75%	🔴 Very rare
engine.env	0	0%	❌ Unused
plugins	0	0%	❌ Unused
tools-timeout	0	0%	❌ Unused

---

2️⃣ Feature Usage Matrix

Feature Category	Available Features	Used	Not Used
Engine Config	model, args, agent, env, command, version	model✅, args✅, agent⚠️	env❌, command❌, version⚠️
Sandbox	awf, srt, mcp-container	awf⚠️	srt❌
Tools - Core	github, bash, edit	github✅, bash✅, edit✅	—
Tools - Extended	playwright, web-fetch, serena	playwright⚠️, web-fetch⚠️, serena✅	—
Tools - Meta	agentic-workflows, cache-memory	cache-memory✅	agentic-workflows⚠️
Tools - Safety	safe-inputs, safe-outputs	safe-outputs✅	safe-inputs⚠️
Tools - Config	tools-timeout, startup-timeout	—	both❌
Plugins	experimental plugin API	—	plugins❌

---

3️⃣ Missed Opportunities

View High Priority Opportunities

🔴 High Priority

Opportunity 1: AWF Sandbox for Web-Fetching Workflows

• What: The AWF network firewall sandbox (sandbox: agent: awf) isolates the Copilot CLI in a container with controlled network access
• Why It Matters: Workflows using web-fetch: or accessing external domains run without sandboxing, creating potential for SSRF or unintended network access
• Where: ~13 workflows with web-fetch: but no AWF sandbox (e.g., cli-consistency-checker.md, craft.md, daily-news.md already has it as a good example)
• How to Implement:

  network:
    allowed:
      - defaults
      - node
  sandbox:
    agent: awf  # Firewall enabled

Opportunity 2: Connect Custom Agent Files to Specialized Workflows

• What: The .github/agents/ directory has 10 custom agent files (technical-doc-writer.agent.md, contribution-checker.agent.md, ci-cleaner.agent.md, etc.) but only 4 workflows use engine.agent:
• Why It Matters: Specialized personas (tone, behavior, domain knowledge) can be centrally maintained and reused across workflows instead of duplicating in each prompt
• Where: Documentation workflows (docs-noob-tester.md, layout-spec-maintainer.md), review workflows (grumpy-reviewer.md), CI workflows (ci-coach.md, ci-doctor.md)
• How to Implement:

  engine:
    id: copilot
    agent: technical-doc-writer  # References .github/agents/technical-doc-writer.agent.md

View Medium Priority Opportunities

🟡 Medium Priority

Opportunity 3: Use engine.env for Configuration

• What: engine.env allows injecting environment variables into the Copilot CLI process
• Why It Matters: Currently 0% adoption - workflows pass configuration as inline text in prompts or bash setup steps when typed env vars would be cleaner
• Where: Workflows needing API endpoints, feature flags, or configuration that varies by environment
• How to Implement:

  engine:
    id: copilot
    env:
      DEBUG_ANALYSIS: "true"
      ANALYSIS_DEPTH: comprehensive
      CUSTOM_API_URL: (internalapi.example.com/redacted)

Opportunity 4: Expand safe-inputs for Complex CLI Operations

• What: safe-inputs provides audited, controlled execution of CLI commands (e.g., safeinputs-gh, safeinputs-go, safeinputs-make)
• Why It Matters: Only 5 workflows use it. Many others use bash: ["*"] wildcard which allows unrestricted command execution
• Where: daily-cli-performance.md shows the pattern well; similar workflows (daily-compiler-quality.md, tidy.md, jsweep.md) could benefit
• How to Implement:

  safe-inputs:
    - id: safeinputs-gh
      cmd: gh
      args-pattern: "^(issue|pr|api|repo) .*"
    - id: safeinputs-make
      cmd: make
      args-pattern: "^(build|test|lint|fmt)$"

Opportunity 5: Use agentic-workflows Tool for Meta-Orchestration

• What: The tools.agentic-workflows MCP server lets a workflow trigger and monitor other workflows
• Why It Matters: Only 3 workflows use it despite significant potential for orchestration (e.g., triggering fix workflows after analysis)
• Where: agent-performance-analyzer.md, workflow-health-manager.md, repository-quality-improver.md could trigger follow-up workflows
• How to Implement:

  tools:
    agentic-workflows:

Opportunity 6: Add tools-timeout for MCP-Heavy Workflows

• What: tools-timeout and startup-timeout control how long MCP tool calls can take
• Why It Matters: 0% adoption. Workflows using multiple heavy MCP servers (serena + playwright + github) can hang indefinitely if a tool call stalls
• Where: smoke-copilot.md, slide-deck-maintainer.md, jsweep.md use 5+ tools simultaneously
• How to Implement:

  tools:
    github:
    serena:
    playwright:
    timeout: 120        # 2 min max per tool call
    startup-timeout: 30 # 30s for MCP server startup

Opportunity 7: Model Selection for Cost/Quality Optimization

• What: engine.model allows specifying the AI model; org-level GH_AW_MODEL_AGENT_COPILOT variable sets the default
• Why It Matters: Only 9 workflows (11.3%) pin a model. Smoke/daily-quick workflows could use cheaper models; complex analysis workflows could use stronger ones
• Where: Simple tasks (detection, labeling, routing) → gpt-5.1-codex-mini; complex analysis → stronger models
• How to Implement:

  # For lightweight/fast workflows
  engine:
    id: copilot
    model: gpt-5.1-codex-mini  # Cost-effective for simple tasks
  
  # For complex analysis
  engine:
    id: copilot
    model: claude-sonnet-4.6  # Higher quality for deep analysis

View Low Priority Opportunities

🟢 Low Priority

Opportunity 8: Explore Plugins for Specialized Tooling

• What: plugins (experimental) allows installing Copilot CLI plugins from GitHub repos before execution
• Why It Matters: 0% adoption. For workflows needing specialized domain tools or MCP servers bundled as plugins
• Where: Future workflows needing domain-specific knowledge bases or specialized APIs
• How to Implement:

  plugins:
    - github/copilot-plugin-example
    - org/custom-domain-tools

Opportunity 9: Granular Bash Permissions vs Wildcard

• What: Many workflows use bash: ["*"] (unrestricted wildcard) when they could list specific commands
• Why It Matters: Reduces attack surface; forces intentional tool use
• Where: Workflows doing specific, known operations (e.g., only need git, grep, awk)
• Note: Trade-off is flexibility vs. security posture

Opportunity 10: Github Tool Toolsets Granularity

• What: The github tool supports toolsets: parameter for filtering which GitHub API operations are available
• Why It Matters: Many workflows use github: without specifying toolsets, granting full GitHub MCP access
• Where: Read-only analysis workflows could restrict to toolsets: [repos, issues] instead of full access
• How to Implement:

  tools:
    github:
      toolsets: [repos, issues, pull_requests]  # Only what's needed

---

4️⃣ Specific Workflow Recommendations

View Workflow-Specific Recommendations

ci-doctor.md - CI Failure Investigator

• Current: Uses engine.model: gpt-5.1-codex-mini ✅, network: defaults ✅
• Missing: No sandbox despite reading external content; no engine.agent for consistent persona
• Recommended: Add sandbox.agent: awf, consider agent: ci-cleaner (already exists in .github/agents/)

grumpy-reviewer.md - PR Review Agent

• Current: Uses standard copilot engine
• Missing: Has dedicated .github/agents/grumpy-reviewer.agent.md but doesn't use engine.agent: to reference it
• Recommended: Add engine: { id: copilot, agent: grumpy-reviewer } to leverage the centrally-maintained agent file

daily-news.md - News Digest (Best Practice Reference ⭐)

• Already Uses: AWF sandbox, cache-memory, web-fetch, network config, custom steps
• Note: This workflow is a great reference for other daily workflows

smoke-copilot.md - Smoke Test

• Current: Very comprehensive - uses 8+ tools including serena, playwright, github, agentic-workflows
• Missing: tools-timeout for the many MCP servers in use
• Recommended: Add tools: { timeout: 120, startup-timeout: 30 } to prevent indefinite hangs

workflow-generator.md / craft.md - Workflow Creation

• Current: Uses bash, edit, web-fetch for generating new workflows
• Missing: engine.agent: agentic-workflows could provide workflow-creation expertise
• Recommended: Use .github/agents/agentic-workflows.agent.md or interactive-agent-designer.agent.md

repository-quality-improver.md - Quality Analysis

• Current: Creates issues with improvement suggestions
• Missing: Could use tools.agentic-workflows to trigger fix workflows after analysis
• Recommended: Add tools: { agentic-workflows: } for automated remediation triggering

---

5️⃣ Trends & Insights

View Historical Trends

This is the first comprehensive analysis. Future runs will track:

• Which recommendations have been implemented
• New Copilot CLI features as they're released
• Changes in feature adoption rates

Architecture Observations

1. Network-First Design: 88.8% configure network settings - strong security posture
2. Persistence via Cache: 83.8% use cache-memory - great pattern adoption
3. Safe-Outputs Universal: All 80 workflows use safe-outputs - excellent
4. Timeout Standard: 95% set timeouts - reliable execution management
5. Serena Growing: 27.5% adoption of serena for code analysis - healthy adoption curve
6. AWF Adoption Lagging: Only 18.8% use AWF despite security benefits
7. Agent Files Disconnected: Agent files exist but aren't linked to matching workflows

---

6️⃣ Best Practice Guidelines

Based on this research:

1. Always enable AWF when using web-fetch or external network access: Protects against SSRF and unintended data exfiltration
2. Link custom agent files to workflows: If .github/agents/ has a relevant agent file, use engine.agent: to reference it for consistent personas
3. Use engine.env instead of hardcoded values: For configuration that might change across environments
4. Add tools-timeout for MCP-heavy workflows: Prevents indefinite hangs when running 4+ MCP servers simultaneously
5. Consider model selection for specialized tasks: gpt-5.1-codex-mini for simple/detection tasks, stronger models for complex analysis
6. Prefer safe-inputs over bash wildcard: For auditable, controlled CLI operations

---

7️⃣ Action Items

Immediate Actions (this week):

• Audit the 13 web-fetch workflows without AWF sandbox and add sandbox: agent: awf
• Connect grumpy-reviewer.md to use engine.agent: grumpy-reviewer
• Connect hourly-ci-cleaner.md to use engine.agent: ci-cleaner (already done ✅)

Short-term (this month):

• Add tools-timeout configuration to smoke-copilot.md and other multi-MCP workflows
• Explore engine.env for workflows that pass config via bash setup steps
• Identify 3-5 candidates for safe-inputs migration from bash: ["*"]

Long-term (this quarter):

• Evaluate plugins (experimental) for domain-specific tooling needs
• Build a model selection guide: which models work best for which workflow categories
• Create a meta-orchestration pattern using tools.agentic-workflows for automated remediation pipelines

---

View Supporting Evidence & Methodology

Research Methodology

Data Collection:

• Analyzed all 154 .md workflow files in .github/workflows/
• Examined Copilot engine source files: copilot_engine.go, copilot_engine_execution.go, copilot_engine_tools.go, copilot_mcp.go
• Reviewed docs/src/content/docs/reference/engines.md and pkg/constants/constants.go
• Cross-referenced feature availability with usage patterns

Analysis Tools: grep, glob, Go constants inspection, YAML frontmatter parsing

Limitations:

• Lock file (.lock.yml) analysis provides compiler output but .md source files are authoritative
• Some features like engine.env may be used in private workflows not visible here
• Model selection effectiveness would require runtime data to evaluate properly

References

• Copilot Engine Source: pkg/workflow/copilot_engine*.go
• Engine Documentation: docs/src/content/docs/reference/engines.md
• Constants: pkg/constants/constants.go
• Custom Agents: .github/agents/*.agent.md
• Repo Memory: Saved to memory/copilot-cli-research branch

---

References:

• §22200448355

AI generated by Copilot CLI Deep Research Agent

• expires on Feb 26, 2026, 9:26 PM UTC