[extension] command.ai-dev: ai-dev command safety extension

[MatthiasLew]

Contribution type

New Extension

Proposed or existing Extension ID

command.ai-dev

Capability boundary

Detects sensitive ai-dev CLI (ai-dev-cli-tools) operations and provides structured evidence that HOL Guard policy can use to require review or enforce configured controls.

Specifically owns evidence detection for:

• Forced overwrites and merges of existing developer IDE and agent MCP configuration files (.codex/config.toml, .cursor/mcp.json, .gemini/settings.json, .mcp.json).
• Lifecycle management of the background file-watching index daemon and local TCP control socket (start and stop).
• Exclusive task lease acquisition and release in multi-agent orchestration state (claim and release).

Lower-risk counterpart clarification:

• ai-dev integrations install [client] without --force is a non-matching counterpart for the forced overwrite rule because it preserves existing configuration files; however, because it may still create initial configuration files and .ai-dev/clients/*.json, it is treated as a lower-risk non-matching write, not as a read-only command.

Out of scope for v1:

• Telemetry commands (telemetry sharing enable, flush), test check runners (check, test), application runtime management (run, stop), cache clearing (cache clear), semantic rebuilds, and task completion. These remain candidates for future coverage once v1 is merged.

Metadata context:

• trustClass: "external"
• activation: "opt-in"
• license: "MIT"
• publisher: {"id": "community.ai-dev", "displayName": "ai-dev community"}
• icon: {"kind": "react-icon", "name": "HiMiniCommandLine", "background": "#2563EB"}

Command surface

• Executables: ai-dev, ai-dev.exe, ai-dev.cmd
• Module invocations: python -m ai_dev_tools, python3 -m ai_dev_tools, py -m ai_dev_tools
• Shell wrappers: exec, xargs (as well as transparent wrappers normalized by Guard)
• Global options: --project <path> (consumes value), --json, --quiet (can appear before, between, or after subcommands)
• Subcommands covered in v1:
  • integrations install [client] [--force]
  • index daemon [start|stop|status] (and bare index daemon, which defaults to start)
  • agents [claim|release|status] <task_id> [--agent <agent_id>]

Destructive or sensitive examples

1. Forced IDE configuration overwrite:
   • ai-dev integrations install codex --force
   • ai-dev integrations install all --force
   • ai-dev integrations install cursor --force
2. Background daemon process start & socket binding:
   • ai-dev index daemon start
   • ai-dev index daemon (defaults to start)
3. Background daemon process termination:
   • ai-dev index daemon stop
4. Exclusive multi-agent task locking:
   • ai-dev agents claim task-42 --agent agent-alpha
5. Multi-agent task lease release:
   • ai-dev agents release task-42 --agent agent-alpha

Safe counterparts

True safe, read-only, and preview/help counterparts:

• integrations install --force safe counterpart:
  • ai-dev integrations install --help
  • ai-dev --help
• index daemon start / stop safe counterparts:
  • ai-dev index daemon status (queries running daemon over local TCP without mutating state)
  • ai-dev index status (reads on-disk repository index metadata)
  • ai-dev index daemon --help
• agents claim / release safe counterparts:
  • ai-dev agents status (read-only inspection of active agent task locks)
  • ai-dev agents claim --help
  • ai-dev agents release --help
• General project read-only / diagnostic counterparts:
  • ai-dev doctor (read-only environment diagnostic report)
  • ai-dev scan (read-only project technology discovery)
  • ai-dev map (read-only repository file tree mapping)
  • ai-dev git status / ai-dev git inspect (read-only git working tree inspection)

Parser and composition edge cases

• Argparse flag abbreviations: Python's argparse resolves unambiguous long-option prefixes, so --f, --fo, --for, --forc, and --force all trigger the forced overwrite condition.
• Unresolved shell expansions: Arguments containing $VAR, ${VAR}, $(...), or backtick command substitutions (e.g. ai-dev integrations install codex $FORCE_FLAG) cannot be proven safe at parse time and are directed to review via an unresolved-expansion matcher.
• Quoted arguments and paths with spaces: ai-dev --project "Workspace/App One" integrations install codex --force and ai-dev agents claim "task with space" --agent "Agent Smith".
• Reordered global options: ai-dev --project ./dir integrations install --force vs ai-dev integrations install codex --force --project ./dir --json.
• Command chaining and separators: ai-dev index daemon start && ai-dev agents claim task-1 --agent a preserves evidence across each command segment.
• Malformed and unsupported inputs: ai-dev integrations install codex --unknown-flag --force and ai-dev index daemon start --invalid-option preserve uncertainty and fail-secure behavior (fail_secure_unknown_options=True), ensuring malformed flags cannot bypass the protection boundary.

Risk and authority model

Proposed rules and initial severities (to be confirmed during proposal review):

• command.ai-dev.integrations-install-force:
  • Proposed severity: high (alternative: medium)
  • Risk class: ("destructive_shell",)
  • Action class: ("ai-dev forced integration config overwrite command",)
  • Default mode: review
  • Safer alternatives: "Run ai-dev integrations install without --force to preserve existing IDE configurations.", "Inspect and back up existing .codex, .cursor, .gemini, or .mcp.json files before forcing."
• command.ai-dev.index-daemon-start:
  • Proposed severity: medium
  • Risk class: ("execution",)
  • Action class: ("ai-dev index daemon lifecycle command",)
  • Default mode: review
  • Safer alternatives: "Check running daemon state with ai-dev index daemon status before starting.", "Run a one-shot repository index with ai-dev index update instead of a persistent daemon."
• command.ai-dev.index-daemon-stop:
  • Proposed severity: medium
  • Risk class: ("destructive_shell", "execution")
  • Action class: ("ai-dev index daemon lifecycle command",)
  • Default mode: review
  • Safer alternatives: "Query daemon health with ai-dev index daemon status before stopping."
• command.ai-dev.agents-claim:
  • Proposed severity: medium
  • Risk class: ("destructive_shell",)
  • Action class: ("ai-dev agent coordination mutation command",)
  • Default mode: review
  • Safer alternatives: "Inspect active agent locks with ai-dev agents status before claiming."
• command.ai-dev.agents-release:
  • Proposed severity: low (alternative: medium)
  • Risk class: ("destructive_shell",)
  • Action class: ("ai-dev agent coordination mutation command",)
  • Default mode: review
  • Safer alternatives: "Verify task ownership with ai-dev agents status before releasing."

Authority boundaries:

• The extension only emits structured MatcherEvidence. Final policy decisions remain under the exclusive authority of HOL Guard's policy engine.
• As an external extension with opt-in activation, these rules remain inert under default baseline evaluation and never weaken required security floors or other matching rules.

Privacy and performance

• Privacy: Matchers parse only executable tokens, subcommand paths, and static flags. Raw command strings, local filesystem paths (e.g. arguments to --project), environment variable names/values, agent IDs, and task IDs are never persisted in MatcherEvidence.detail or stored in extension catalog objects.
• Performance: Matchers evaluate against pre-indexed executable sets (executable_names) with early termination on non-matching segments. Option parsing utilizes bounded, single-pass argument scans matching the canonical command tokens without invoking external interpreters.

Authoritative references

• Repository: https://github.com/MatthiasLew/ai-dev-cli-tools
• CLI entrypoint & parser: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/cli.py
• Integration install logic: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/integrations.py
• Index daemon service: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/index_daemon_service.py
• Agent coordination service: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/runners/coordination.py

Readiness checklist

• I searched the Extension directory and existing issues for overlapping coverage.
• I removed secrets, credentials, private command history, and local paths from these examples.
• I can contribute or help validate destructive and safe-counterpart tests.

[kantorcodes]

Contribution type

New Extension

Proposed or existing Extension ID

command.ai-dev

Capability boundary

Detects sensitive ai-dev CLI (ai-dev-cli-tools) operations and provides structured evidence that HOL Guard policy can use to require review or enforce configured controls.

Specifically owns evidence detection for:

• Forced overwrites and merges of existing developer IDE and agent MCP configuration files (.codex/config.toml, .cursor/mcp.json, .gemini/settings.json, .mcp.json).
• Lifecycle management of the background file-watching index daemon and local TCP control socket (start and stop).
• Exclusive task lease acquisition and release in multi-agent orchestration state (claim and release).

Lower-risk counterpart clarification:

• ai-dev integrations install [client] without --force is a non-matching counterpart for the forced overwrite rule because it preserves existing configuration files; however, because it may still create initial configuration files and .ai-dev/clients/*.json, it is treated as a lower-risk non-matching write, not as a read-only command.

Out of scope for v1:

• Telemetry commands (telemetry sharing enable, flush), test check runners (check, test), application runtime management (run, stop), cache clearing (cache clear), semantic rebuilds, and task completion. These remain candidates for future coverage once v1 is merged.

Metadata context:

• trustClass: "external"
• activation: "opt-in"
• license: "MIT"
• publisher: {"id": "community.ai-dev", "displayName": "ai-dev community"}
• icon: {"kind": "react-icon", "name": "HiMiniCommandLine", "background": "#2563EB"}

Command surface

• Executables: ai-dev, ai-dev.exe, ai-dev.cmd

• Module invocations: python -m ai_dev_tools, python3 -m ai_dev_tools, py -m ai_dev_tools

• Shell wrappers: exec, xargs (as well as transparent wrappers normalized by Guard)

• Global options: --project <path> (consumes value), --json, --quiet (can appear before, between, or after subcommands)

• Subcommands covered in v1:

  • integrations install [client] [--force]
  • index daemon [start|stop|status] (and bare index daemon, which defaults to start)
  • agents [claim|release|status] <task_id> [--agent <agent_id>]

Destructive or sensitive examples

1. Forced IDE configuration overwrite:

   • ai-dev integrations install codex --force
   • ai-dev integrations install all --force
   • ai-dev integrations install cursor --force

2. Background daemon process start & socket binding:

   • ai-dev index daemon start
   • ai-dev index daemon (defaults to start)

3. Background daemon process termination:

   • ai-dev index daemon stop

4. Exclusive multi-agent task locking:

   • ai-dev agents claim task-42 --agent agent-alpha

5. Multi-agent task lease release:

   • ai-dev agents release task-42 --agent agent-alpha

Safe counterparts

True safe, read-only, and preview/help counterparts:

• integrations install --force safe counterpart:

  • ai-dev integrations install --help
  • ai-dev --help

• index daemon start / stop safe counterparts:

  • ai-dev index daemon status (queries running daemon over local TCP without mutating state)
  • ai-dev index status (reads on-disk repository index metadata)
  • ai-dev index daemon --help

• agents claim / release safe counterparts:

  • ai-dev agents status (read-only inspection of active agent task locks)
  • ai-dev agents claim --help
  • ai-dev agents release --help

• General project read-only / diagnostic counterparts:

  • ai-dev doctor (read-only environment diagnostic report)
  • ai-dev scan (read-only project technology discovery)
  • ai-dev map (read-only repository file tree mapping)
  • ai-dev git status / ai-dev git inspect (read-only git working tree inspection)

Parser and composition edge cases

• Argparse flag abbreviations: Python's argparse resolves unambiguous long-option prefixes, so --f, --fo, --for, --forc, and --force all trigger the forced overwrite condition.
• Unresolved shell expansions: Arguments containing $VAR, ${VAR}, $(...), or backtick command substitutions (e.g. ai-dev integrations install codex $FORCE_FLAG) cannot be proven safe at parse time and are directed to review via an unresolved-expansion matcher.
• Quoted arguments and paths with spaces: ai-dev --project "Workspace/App One" integrations install codex --force and ai-dev agents claim "task with space" --agent "Agent Smith".
• Reordered global options: ai-dev --project ./dir integrations install --force vs ai-dev integrations install codex --force --project ./dir --json.
• Command chaining and separators: ai-dev index daemon start && ai-dev agents claim task-1 --agent a preserves evidence across each command segment.
• Malformed and unsupported inputs: ai-dev integrations install codex --unknown-flag --force and ai-dev index daemon start --invalid-option preserve uncertainty and fail-secure behavior (fail_secure_unknown_options=True), ensuring malformed flags cannot bypass the protection boundary.

Risk and authority model

Proposed rules and initial severities (to be confirmed during proposal review):

• command.ai-dev.integrations-install-force:

  • Proposed severity: high (alternative: medium)
  • Risk class: ("destructive_shell",)
  • Action class: ("ai-dev forced integration config overwrite command",)
  • Default mode: review
  • Safer alternatives: "Run ai-dev integrations install without --force to preserve existing IDE configurations.", "Inspect and back up existing .codex, .cursor, .gemini, or .mcp.json files before forcing."

• command.ai-dev.index-daemon-start:

  • Proposed severity: medium
  • Risk class: ("execution",)
  • Action class: ("ai-dev index daemon lifecycle command",)
  • Default mode: review
  • Safer alternatives: "Check running daemon state with ai-dev index daemon status before starting.", "Run a one-shot repository index with ai-dev index update instead of a persistent daemon."

• command.ai-dev.index-daemon-stop:

  • Proposed severity: medium
  • Risk class: ("destructive_shell", "execution")
  • Action class: ("ai-dev index daemon lifecycle command",)
  • Default mode: review
  • Safer alternatives: "Query daemon health with ai-dev index daemon status before stopping."

• command.ai-dev.agents-claim:

  • Proposed severity: medium
  • Risk class: ("destructive_shell",)
  • Action class: ("ai-dev agent coordination mutation command",)
  • Default mode: review
  • Safer alternatives: "Inspect active agent locks with ai-dev agents status before claiming."

• command.ai-dev.agents-release:

  • Proposed severity: low (alternative: medium)
  • Risk class: ("destructive_shell",)
  • Action class: ("ai-dev agent coordination mutation command",)
  • Default mode: review
  • Safer alternatives: "Verify task ownership with ai-dev agents status before releasing."

Authority boundaries:

• The extension only emits structured MatcherEvidence. Final policy decisions remain under the exclusive authority of HOL Guard's policy engine.
• As an external extension with opt-in activation, these rules remain inert under default baseline evaluation and never weaken required security floors or other matching rules.

Privacy and performance

• Privacy: Matchers parse only executable tokens, subcommand paths, and static flags. Raw command strings, local filesystem paths (e.g. arguments to --project), environment variable names/values, agent IDs, and task IDs are never persisted in MatcherEvidence.detail or stored in extension catalog objects.
• Performance: Matchers evaluate against pre-indexed executable sets (executable_names) with early termination on non-matching segments. Option parsing utilizes bounded, single-pass argument scans matching the canonical command tokens without invoking external interpreters.

Authoritative references

• Repository: https://github.com/MatthiasLew/ai-dev-cli-tools
• CLI entrypoint & parser: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/cli.py
• Integration install logic: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/integrations.py
• Index daemon service: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/index_daemon_service.py
• Agent coordination service: https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/src/ai_dev_tools/runners/coordination.py

Readiness checklist

• I searched the Extension directory and existing issues for overlapping coverage.[x] I removed secrets, credentials, private command history, and local paths from these examples.[x] I can contribute or help validate destructive and safe-counterpart tests.

Hi Matthew!

This proposal looks great, feel free to submit a PR.