Skip to content
This repository was archived by the owner on Nov 5, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"name": "microsoft-managed-apps",
"source": "./plugins/microsoft-managed-apps",
"description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.",
"version": "2.1.7"
"version": "2.1.8"
}
]
}
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "microsoft-managed-apps",
"version": "2.1.7",
"version": "2.1.8",
"description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.",
"author": {
"name": "Microsoft",
Expand Down
3 changes: 3 additions & 0 deletions plugins/microsoft-managed-apps/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,9 @@ Claude and legacy Copilot discover `hooks/hooks.json`.
Agent Plugins Copilot discovers `com.github.copilot/hooks/hooks.json`.
The latter uses native Copilot events, `${PLUGIN_ROOT}`, and the same scripts.
Validation checks both configurations for equivalent scripts, matchers, and timeouts.
Only the native Copilot entry point passes `--github-copilot` / `-GitHubCopilot` to report `MS_PLUGIN_REPORT_AGENT=github-copilot`.
Shared hooks must remove inherited reports. Do not detect the host from environment markers or shell type.
Keep the agent report independent of `MS_CLI_ORIGIN=plugin` and user-provided origin overrides.
Keep both hook payload contracts when editing a script.

The canonical manifest follows [Agent Plugins 1.0.0](https://agent-plugins.org/specification).
Expand Down
7 changes: 6 additions & 1 deletion plugins/microsoft-managed-apps/QUICKSTART.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,12 @@ After the first `ms app create`, the project folder gets a `memory-bank.md`. Ope

### Telemetry

The plugin tags the `ms` CLI commands it runs (via an `MS_CLI_ORIGIN` attribution prefix) so usage can be attributed to this plugin. It adds no new data collection and you can opt out by setting `MS_CLI_ORIGIN` yourself. See the [Telemetry section in the README](./README.md#telemetry) for details.
The plugin defaults `MS_CLI_ORIGIN` to `plugin` for commands that invoke `ms`.
It preserves existing origin values.
The native Copilot hook separately sets `MS_PLUGIN_REPORT_AGENT=github-copilot`.
Shared hooks remove inherited agent reports.
An origin override does not disable telemetry.
See the [Telemetry section in the README](./README.md#telemetry) for details.

### Uninstall

Expand Down
44 changes: 37 additions & 7 deletions plugins/microsoft-managed-apps/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,8 @@ To evaluate a local checkout containing these changes:
**Compatibility status:** the portable package does not establish full Codex runtime support.
Skills use document-relative links to shared resources. They do not require `${CLAUDE_PLUGIN_ROOT}`.
The package does not provide a Codex architect agent or Codex hooks.
Shared instructions request `plugin/codex` attribution while preserving an existing `MS_CLI_ORIGIN` value.
Shared instructions request `MS_CLI_ORIGIN=plugin` while preserving an existing value.
They do not set `MS_PLUGIN_REPORT_AGENT` because the shared instructions do not identify the host.
This attribution depends on the agent following instructions, not hook enforcement.
Complete the client checks below before using workflows that change resources.

Expand Down Expand Up @@ -219,6 +220,8 @@ Run the client's enable/disable actions and confirm that the same components ret
For each supported Claude and Copilot runtime, run `ms --version` through a shell tool.
Capture the rewritten command or CLI attribution evidence.
Repeat with `MS_CLI_ORIGIN=review/custom` already set and confirm that the hook preserves it.
Check that the native Copilot entry point also sets `MS_PLUGIN_REPORT_AGENT=github-copilot`.
Check that shared hooks remove inherited reports, even when agent environment markers exist.
Check session-start guidance and the daily version-check instructions.
Run `/create-app` and a representative `/add-*` only in an authorized test environment.
For Codex, verify the documented instruction-based attribution instead of expecting a hook.
Expand All @@ -234,14 +237,41 @@ Describe the app in the command and the skill generates its name, plans the comp

## Telemetry

This plugin sets an attribution tag on the `@microsoft/managed-apps-cli` (`ms`) commands it runs. A `PreToolUse` hook (`hooks/pre-tool-use.sh` / `.ps1`) transparently prefixes every shell command that invokes `ms` with `MS_CLI_ORIGIN=plugin/<host-agent>` (e.g. `plugin/claude-code`, `plugin/copilot-cli`). This tells the CLI's telemetry that the invocation originated from this plugin — it does **not** add any new data collection beyond what the `ms` CLI already reports, and it never blocks or alters the behavior of your command.
This plugin marks commands that invoke `@microsoft/managed-apps-cli` (`ms`) with `MS_CLI_ORIGIN=plugin`.
The CLI uses this value as `cliSource`, the source of the command.
The [Bash hook](hooks/pre-tool-use.sh) and [PowerShell hook](hooks/pre-tool-use.ps1) apply this default before tool execution.
They preserve existing origin values, including empty values and inline assignments.
They leave non-`ms` commands unchanged and do not transmit telemetry themselves.

- **What it does:** tags `ms` CLI runs so usage can be attributed to this plugin.
- **What it does not do:** it does not run for non-`ms` commands, and it does not transmit anything itself.
- **Opting out:** set `MS_CLI_ORIGIN` yourself (in your shell environment or inline on the command) and the hook leaves your value untouched. You can also disable the hook by removing/editing `hooks/hooks.json`, or refer to the `ms` CLI documentation for its own telemetry controls.
Agent identity is separate from command origin.
Only a known host-specific entry point supplies `MS_PLUGIN_REPORT_AGENT`.
The plugin does not inspect agent environment markers.

For Agent Plugins Copilot, the hook configuration is `com.github.copilot/hooks/hooks.json`.
Disable hooks in the client's settings rather than editing only the legacy configuration.
| Entry point within this plugin | Agent report |
| --- | --- |
| [com.github.copilot/hooks/hooks.json](com.github.copilot/hooks/hooks.json) | Fixed `github-copilot`, selected by the hook argument `--github-copilot` or `-GitHubCopilot`. |
| [hooks/hooks.json](hooks/hooks.json), shared by Claude Code and legacy Copilot | Omitted. This configuration does not identify one host. |
| Shared skills, including Codex and Cursor consumers | Omitted. No host-specific reporting hook exists. |

The native report identifies Copilot without claiming CLI or VS Code.
It replaces an inherited report and remains independent of any origin override.
Shared hooks remove inherited reports before the command executes.
They remove the variable rather than set an empty value, so stale reports cannot bypass CLI detection.
The `.claude-plugin` directory and shell type do not identify the host.

The CLI treats a supplied report as authoritative.
A recognized report determines the agent name without environment-marker detection.
An empty or unrecognized report produces `unknown` without fallback detection.
Only an absent report allows the CLI to detect the agent from environment markers.
This change does not add model detection or a CLI agent-selection option.

Older CLI versions receive `plugin` instead of `plugin/<host-agent>` and ignore the new report.
Release CLI support for the separate report before this plugin when continuous agent attribution is required.

To override the origin, set `MS_CLI_ORIGIN` in your shell environment or inline on the command.
An origin override is not a telemetry opt-out.
Use the CLI's telemetry controls to disable telemetry.
To disable hooks, use the client's settings rather than editing only the shared hook configuration.

## Uninstall

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,15 @@
"type": "command",
"bash": "bash \"${PLUGIN_ROOT}/hooks/session-start.sh\"",
"powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}/hooks/session-start.ps1\"",
"env": { "COPILOT_CLI": "1" },
"timeoutSec": 5
}
],
"preToolUse": [
{
"type": "command",
"matcher": "Bash|bash|shell|sh|execute|execute_command|run_in_terminal|terminal|powershell|PowerShell|pwsh",
"bash": "bash \"${PLUGIN_ROOT}/hooks/pre-tool-use.sh\"",
"powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}/hooks/pre-tool-use.ps1\"",
"env": { "COPILOT_CLI": "1" },
"bash": "bash \"${PLUGIN_ROOT}/hooks/pre-tool-use.sh\" --github-copilot",
"powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}/hooks/pre-tool-use.ps1\" -GitHubCopilot",
"timeoutSec": 5
}
]
Expand Down
55 changes: 30 additions & 25 deletions plugins/microsoft-managed-apps/hooks/pre-tool-use.ps1
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# PreToolUse hook (PowerShell): for any shell command that invokes the `ms`
# CLI (the @microsoft/managed-apps-cli binary), default MS_CLI_ORIGIN to
# `plugin/<host-agent>` (e.g. plugin/claude-code, plugin/copilot-cli, or
# plugin/unknown) for that invocation. Every CLI command run by this plugin
# or any of its skills is thereby attributed for telemetry.
# CLI (the @microsoft/managed-apps-cli binary), default MS_CLI_ORIGIN to `plugin`.
# Only the native Copilot entry point passes -GitHubCopilot to report
# MS_PLUGIN_REPORT_AGENT=github-copilot. Shared hooks remove inherited reports.
#
# Behavior:
# - If the command does not invoke `ms`, allow unchanged.
# - If the command already sets MS_CLI_ORIGIN inline, allow unchanged.
# - Preserve inline MS_CLI_ORIGIN assignments. A native agent report
# remains independent of the origin override.
# - Otherwise, rewrite the command via hookSpecificOutput.updatedInput
# (Claude) and modifiedArgs (Copilot). The
# rewrite defaults MS_CLI_ORIGIN only when it is truly unset
Expand All @@ -18,21 +18,11 @@
# The hook never blocks; any failure falls through to the unchanged "allow"
# decision (telemetry attribution must never block a developer's workflow).

param([switch]$GitHubCopilot)

$ErrorActionPreference = 'Stop'

$PLUGIN_ID = 'plugin'

# Detect the host agent so telemetry can split plugin attribution by which
# CLI ran the command. Falls back to "unknown" rather than dropping the
# suffix so the format (plugin/host) is stable for downstream parsers.
if ($env:CLAUDECODE -eq '1' -or $env:CLAUDE_CODE_ENTRYPOINT) {
$HOST_AGENT = 'claude-code'
} elseif ($env:COPILOT_CLI -eq '1' -or $env:COPILOT_AGENT_SESSION_ID) {
$HOST_AGENT = 'copilot-cli'
} else {
$HOST_AGENT = 'unknown'
}
$ORIGIN_VALUE = "$PLUGIN_ID/$HOST_AGENT"
$ORIGIN_VALUE = 'plugin'
$ALLOW_UNCHANGED = '{"permissionDecision":"allow","hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'

function Write-AllowUnchanged {
Expand All @@ -52,13 +42,13 @@ function Write-AllowWithRewrite {
$updated['command'] = $NewCommand
$payload = @{
permissionDecision = 'allow'
permissionDecisionReason = 'Auto-set MS_CLI_ORIGIN for @microsoft/managed-apps-cli attribution'
permissionDecisionReason = 'Set plugin attribution for @microsoft/managed-apps-cli'
updatedInput = $updated
modifiedArgs = $updated
hookSpecificOutput = @{
hookEventName = 'PreToolUse'
permissionDecision = 'allow'
permissionDecisionReason = 'Auto-set MS_CLI_ORIGIN for @microsoft/managed-apps-cli attribution'
permissionDecisionReason = 'Set plugin attribution for @microsoft/managed-apps-cli'
updatedInput = $updated
}
}
Expand Down Expand Up @@ -112,13 +102,13 @@ try {
$msPattern = '(^|[;&|()\n\r])\s*([A-Za-z_][A-Za-z0-9_]*=\S*\s+)*ms(\s+\S|\s*$)'
if ($command -notmatch $msPattern) { Write-AllowUnchanged }

# Already explicitly set in the command itself? Don't touch. The boundary
# Preserve explicit origin assignments. The boundary
# mirrors $msPattern (start-of-command or a real chain separator, plus any
# leading env-prefix assignments) so inline assignments — including ones
# that follow other env prefixes like `FOO=bar MS_CLI_ORIGIN=mine ms ...`
# — are recognized too.
$inlinePattern = '(^|[;&|()\n\r])\s*([A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(export\s+MS_CLI_ORIGIN=|set\s+MS_CLI_ORIGIN=|MS_CLI_ORIGIN=|\$env:MS_CLI_ORIGIN\s*=)'
if ($command -match $inlinePattern) { Write-AllowUnchanged }
$inlineOrigin = $command -match $inlinePattern

# Native Copilot payloads identify the actual shell. Legacy payloads
# retain the existing platform-based fallback.
Expand All @@ -127,11 +117,19 @@ try {
$isPowerShellTool = $toolName.ToLowerInvariant() -in @('powershell', 'pwsh')
}

$prefix = ''
if ($isPowerShellTool) {
# Assign only when the env var does not exist, so a user-set
# $env:MS_CLI_ORIGIN wins at exec time — including an empty value,
# which `Test-Path Env:` treats as "set" (unlike `-not $env:...`).
$newCommand = "if (-not (Test-Path Env:MS_CLI_ORIGIN)) { `$env:MS_CLI_ORIGIN = '$ORIGIN_VALUE' }; $command"
if (-not $inlineOrigin) {
$prefix = "if (-not (Test-Path Env:MS_CLI_ORIGIN)) { `$env:MS_CLI_ORIGIN = '$ORIGIN_VALUE' }; "
}
if ($GitHubCopilot) {
$prefix += "`$env:MS_PLUGIN_REPORT_AGENT = 'github-copilot'; "
} else {
$prefix += "`$env:MS_PLUGIN_REPORT_AGENT = `$null; "
}
} else {
# `${VAR-default}` (no colon) expands to the default ONLY when VAR is
# unset, so any pre-existing user value — including an intentionally-
Expand All @@ -140,10 +138,17 @@ try {
# only `$ORIGIN_VALUE` is expanded here. The `&&` chain runs the export
# before the user command, and `export` makes the value visible to
# chained segments and to the spawned `ms` process.
$newCommand = "export MS_CLI_ORIGIN=`"`${MS_CLI_ORIGIN-$ORIGIN_VALUE}`" && $command"
if (-not $inlineOrigin) {
$prefix = "export MS_CLI_ORIGIN=`"`${MS_CLI_ORIGIN-$ORIGIN_VALUE}`" && "
}
if ($GitHubCopilot) {
$prefix += "export MS_PLUGIN_REPORT_AGENT='github-copilot' && "
} else {
$prefix += "unset -v MS_PLUGIN_REPORT_AGENT && "
}
}

Write-AllowWithRewrite -NewCommand $newCommand -OriginalInput $inputHash
Write-AllowWithRewrite -NewCommand ($prefix + $command) -OriginalInput $inputHash
} catch {
# Any unexpected failure: fall through to allow-unchanged so we never
# block the user's command.
Expand Down
68 changes: 30 additions & 38 deletions plugins/microsoft-managed-apps/hooks/pre-tool-use.sh
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
#!/usr/bin/env bash
# PreToolUse hook: for any shell command that invokes the `ms` CLI (the
# @microsoft/managed-apps-cli binary), default MS_CLI_ORIGIN to
# `plugin/<host-agent>` (e.g. plugin/claude-code, plugin/copilot-cli, or
# plugin/unknown) for that invocation so every CLI call made by this plugin
# (or any of its skills) is attributed for telemetry purposes.
# @microsoft/managed-apps-cli binary), default MS_CLI_ORIGIN to `plugin`.
# Only the native Copilot entry point passes --github-copilot to report
# MS_PLUGIN_REPORT_AGENT=github-copilot. Shared hooks remove inherited reports.
#
# Behavior:
# - If the command does not invoke `ms`, allow unchanged.
# - If the command already sets MS_CLI_ORIGIN= inline (env-prefix, `set`,
# or `$env:`), allow unchanged.
# - Preserve inline MS_CLI_ORIGIN assignments. A native agent report
# remains independent of the origin override.
# - Otherwise, rewrite the command via hookSpecificOutput.updatedInput
# (Claude) and modifiedArgs (Copilot). The
# rewrite defaults MS_CLI_ORIGIN only when it is truly unset
Expand Down Expand Up @@ -46,7 +45,7 @@ else
exit 0
fi

# Single-pass python: parse, detect, decide, emit. Uses stdin for the JSON
# Single-pass python: parse, rewrite, emit. Uses stdin for the JSON
# (no argv size limit) and emits exactly one JSON object on stdout. Any
# uncaught exception falls through to the bash-level fallback below.
PYTHON_SCRIPT=$(cat <<'PY'
Expand All @@ -56,19 +55,8 @@ ALLOW_UNCHANGED = json.dumps({
"permissionDecision": "allow",
"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"},
})
PLUGIN_ID = "plugin"

# Detect the host agent so telemetry can split plugin attribution by which
# CLI ran the command. Falls back to "unknown" rather than dropping the
# suffix so the format (plugin/host) is stable for downstream parsers.
import os
if os.environ.get("CLAUDECODE") == "1" or os.environ.get("CLAUDE_CODE_ENTRYPOINT"):
HOST = "claude-code"
elif os.environ.get("COPILOT_CLI") == "1" or os.environ.get("COPILOT_AGENT_SESSION_ID"):
HOST = "copilot-cli"
else:
HOST = "unknown"
ORIGIN_VALUE = PLUGIN_ID + "/" + HOST
ORIGIN_VALUE = "plugin"
github_copilot = sys.argv[1:] == ["--github-copilot"]

def emit_allow():
print(ALLOW_UNCHANGED)
Expand Down Expand Up @@ -111,44 +99,48 @@ ms_pattern = re.compile(
if not ms_pattern.search(command):
emit_allow()

# Already explicitly set in the command itself? Don't touch. The boundary
# Preserve explicit origin assignments. The boundary
# mirrors ms_pattern (start-of-command or a real chain separator, plus any
# leading env-prefix assignments) so inline assignments — including ones that
# follow other env prefixes like `FOO=bar MS_CLI_ORIGIN=mine ms ...` — are
# recognized too.
inline_pattern = re.compile(
r"(?:^|[;&|()\n\r])\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:export\s+MS_CLI_ORIGIN=|set\s+MS_CLI_ORIGIN=|MS_CLI_ORIGIN=|\$env:MS_CLI_ORIGIN\s*=)"
)
if inline_pattern.search(command):
emit_allow()
inline_origin = bool(inline_pattern.search(command))

is_powershell = tool_name.lower() in ("powershell", "pwsh")
prefix = ""
if is_powershell:
# PowerShell: assign only when the env var does not exist, so a user-set
# $env:MS_CLI_ORIGIN wins at exec time — including an empty value, which
# `Test-Path Env:` correctly treats as "set" (unlike `-not $env:...`).
new_command = (
"if (-not (Test-Path Env:MS_CLI_ORIGIN)) { $env:MS_CLI_ORIGIN = '"
+ ORIGIN_VALUE
+ "' }; "
+ command
)
if not inline_origin:
prefix = (
"if (-not (Test-Path Env:MS_CLI_ORIGIN)) { $env:MS_CLI_ORIGIN = '"
+ ORIGIN_VALUE
+ "' }; "
)
if github_copilot:
prefix += "$env:MS_PLUGIN_REPORT_AGENT = 'github-copilot'; "
else:
prefix += "$env:MS_PLUGIN_REPORT_AGENT = $null; "
else:
# Bash: ${VAR-default} (no colon) expands to the default ONLY when VAR is
# unset, so any pre-existing user value — including an intentionally-empty
# one — is preserved at exec time. The `&&` chain ensures the export runs
# before the user command, and `export` makes the value visible to chained
# segments (`cd app && ms app deploy`) and to the spawned `ms` process.
new_command = (
'export MS_CLI_ORIGIN="${MS_CLI_ORIGIN-'
+ ORIGIN_VALUE
+ '}" && '
+ command
)
if not inline_origin:
prefix = 'export MS_CLI_ORIGIN="${MS_CLI_ORIGIN-' + ORIGIN_VALUE + '}" && '
if github_copilot:
prefix += "export MS_PLUGIN_REPORT_AGENT='github-copilot' && "
else:
prefix += "unset -v MS_PLUGIN_REPORT_AGENT && "

updated = dict(tool_input)
updated["command"] = new_command
reason = "Auto-set MS_CLI_ORIGIN for @microsoft/managed-apps-cli attribution"
updated["command"] = prefix + command
reason = "Set plugin attribution for @microsoft/managed-apps-cli"
# Keep legacy fields, native Copilot modifiedArgs, and the Claude wrapper.
print(json.dumps({
"permissionDecision": "allow",
Expand All @@ -165,7 +157,7 @@ print(json.dumps({
PY
)

OUTPUT=$(printf '%s' "$INPUT_JSON" | $PYTHON_BIN -c "$PYTHON_SCRIPT" 2>/dev/null)
OUTPUT=$(printf '%s' "$INPUT_JSON" | $PYTHON_BIN -c "$PYTHON_SCRIPT" "$@" 2>/dev/null)
if [ -z "$OUTPUT" ]; then
printf '%s\n' "$ALLOW_UNCHANGED"
else
Expand Down
Loading
Loading