feat(integrations): support SPECIFY_<KEY>_EXTRA_ARGS env var for agent subprocess flags

[doquanghuy]

Description

Closes #2595.

Adds a per-integration env-var hook
(SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS) so operators can inject
extra CLI flags into the spawned agent subprocess without modifying
any SKILL or workflow YAML. The motivating use case is
non-interactive contexts (CI, batch, sandboxed eval) where the
spawned <agent> -p ... hangs silently on an internal permission
or input prompt invisible to the parent specify workflow run
process.

The INTEGRATION segment scopes the variable to this subsystem so
it does not collide with other Spec Kit env-var namespaces.

What changed

• New helper IntegrationBase._apply_extra_args_env_var(args) —
  reads SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS from env (key
  normalized: - → _, uppercased), parses with shlex.split,
  and appends to args. No-op when the env var is unset or
  whitespace-only.
• MarkdownIntegration.build_exec_args,
  TomlIntegration.build_exec_args, and
  SkillsIntegration.build_exec_args each call the helper between
  args = [self.key, "-p", prompt] and the model / output-format
  appends — so extra args sit between -p prompt and the
  canonical Spec Kit flags and cannot clobber them.
• The four integrations that override build_exec_args
  (CodexIntegration, DevinIntegration, OpencodeIntegration,
  CopilotIntegration) also call the helper in the matching
  position so the env var works for every requires_cli
  integration.
• CopilotIntegration.dispatch_command builds cli_args inline
  rather than going through build_exec_args; the hook is invoked
  there too so workflow execution honours the env var (not just
  build_exec_args callers).
• New tests/integrations/test_extra_args.py with 14 tests
  covering: default no-op, single-token, multi-token via shlex,
  whitespace-only treated as unset, other-integration env var
  ignored (per-key scoping), key normalization
  (kiro-cli → KIRO_CLI), requires_cli: False short-circuit,
  per-integration build_exec_args checks for Codex/Devin/
  Opencode/Copilot, Opencode precedence vs. prompt-derived
  --command, and end-to-end dispatch_command checks (Copilot
  override path + inherited base path).

Default behaviour preserved

When SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS is unset for the active
integration, build_exec_args returns byte-identical argv to
before this change. Existing operators see no difference.

Examples

# Non-interactive Claude run in CI
SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions" \
    specify workflow run my-pipeline

# Per-integration scoping
SPECIFY_INTEGRATION_GEMINI_EXTRA_ARGS="--max-turns 3" specify workflow run …

# Multi-token via shlex
SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions --max-turns 3" …

# Hyphenated keys
SPECIFY_INTEGRATION_KIRO_CLI_EXTRA_ARGS="--some-flag" specify workflow run …

Testing

• Tested locally with uv run specify --help
• Ran existing tests: pytest tests/ -q →
  2950 passed, 35 skipped (was 2936 before; +14 new tests
  added in this PR).
• Tested with a sample project: invoked specify workflow run
  against a Claude command step with
  SPECIFY_INTEGRATION_CLAUDE_EXTRA_ARGS=--dangerously-skip-permissions
  set — flag reaches the spawned claude -p ... subprocess
  and the run completes non-interactively. Same workflow
  without the env var still hangs as before (consistent with
  the pre-PR behaviour).

Manual test results

Agent: Claude Code (CLI) | OS/Shell: macOS 14 / zsh

Test	Result	Notes
Env var set → flag in argv	PASS	--dangerously-skip-permissions appears between -p prompt and --model
Env var unset → byte-identical argv	PASS	argv matches pre-PR shape exactly
Other-integration env var ignored	PASS	SPECIFY_INTEGRATION_GEMINI_EXTRA_ARGS=... does not affect Claude argv
Multi-token via shlex	PASS	"--flag-a --flag-b 3" splits into 3 tokens
Whitespace-only treated as unset	PASS	" " → no-op
Key normalization kiro-cli → KIRO_CLI	PASS	env var SPECIFY_INTEGRATION_KIRO_CLI_EXTRA_ARGS correctly read
requires_cli: False short-circuit	PASS	build_exec_args returns None; env-var hook never reached

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (described below)

Used Claude Opus to draft the implementation (env-var hook +
helper extraction), the test suite, the issue body for #2595, and
this PR body. The reproducer scenario (non-interactive claude -p
hang on permission prompts) was a real-world problem encountered
in operator practice. Code, tests, and design decisions were
human-reviewed before submission.

[Copilot]

Pull request overview

Adds a generic env-var hook SPECIFY_<KEY>_EXTRA_ARGS so operators can append CLI flags to the spawned agent subprocess (e.g. --dangerously-skip-permissions for Claude in CI/non-interactive contexts) without editing skills, workflows, or integration code. The hook is implemented once on IntegrationBase and invoked from the three concrete build_exec_args implementations in base.py.

Changes:

• New IntegrationBase._apply_extra_args_env_var helper that reads SPECIFY_<KEY>_EXTRA_ARGS, normalizes the key (hyphens→underscores, uppercased), and shlex.splits the value into args.
• MarkdownIntegration, TomlIntegration, and SkillsIntegration build_exec_args now call the helper between [key, -p, prompt] and the --model / --output-format flags.
• Adds tests/integrations/test_extra_args.py covering no-op default, single/multi-token parsing, whitespace handling, per-integration scoping, key normalization, and requires_cli=False short-circuit.

Show a summary per file

File	Description
src/specify_cli/integrations/base.py	Adds _apply_extra_args_env_var helper and calls it from the three concrete build_exec_args implementations.
tests/integrations/test_extra_args.py	New test module exercising the env-var hook through stub SkillsIntegration subclasses.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 2

[doquanghuy]

Pushed 8341c12 addressing both Copilot findings:

1. Override integrations wired up. CodexIntegration, DevinIntegration, OpencodeIntegration, and CopilotIntegration each override build_exec_args — they now call self._apply_extra_args_env_var(args) between the base argv and the canonical Spec Kit flags. So SPECIFY_CODEX_EXTRA_ARGS, SPECIFY_DEVIN_EXTRA_ARGS, SPECIFY_OPENCODE_EXTRA_ARGS, and SPECIFY_COPILOT_EXTRA_ARGS all reach their respective subprocesses, matching the documented "every requires_cli integration" contract.

2. Test fixture cleanup. Replaced inline __import__("os").environ with a top-of-file import os.

Coverage. Added 4 parameterized override-integration tests locking the wiring per agent — full suite is now 2947 passed (was 2943), 35 skipped, no regressions.

Drive-by. Pyright surfaced a pre-existing latent Optional[dict].get(...) access at copilot/__init__.py:362. Fixed it inline using the same guard pattern already used in base.py for the same access — no behaviour change in practice (every concrete integration sets registrar_config), but the type check now passes cleanly.

AI disclosure: drafted with Claude Opus, human-reviewed.

[Copilot]

Copilot's findings

Comments suppressed due to low confidence (1)

src/specify_cli/integrations/copilot/init.py:149

• CopilotIntegration overrides dispatch_command() and constructs its own cli_args without calling _apply_extra_args_env_var. Since workflow command steps call impl.dispatch_command(...), SPECIFY_COPILOT_EXTRA_ARGS will not actually reach the spawned copilot subprocess in workflows even though build_exec_args() now supports it. Apply the env-var hook in dispatch_command() as well (ideally right after cli_args = ["copilot", "-p", prompt] and before adding --agent/--yolo/--model/--output-format so canonical flags still win).

        args = ["copilot", "-p", prompt]
        self._apply_extra_args_env_var(args)
        if _allow_all():
            args.append("--yolo")
        if model:
            args.extend(["--model", model])
        if output_json:
            args.extend(["--output-format", "json"])
        return args

• Files reviewed: 6/6 changed files
• Comments generated: 2

[doquanghuy]

Pushed a17b951 addressing both new Copilot findings:

1. Opencode ordering fix. Moved self._apply_extra_args_env_var(args) to immediately after args = [self.key, "run"], before the prompt-parsing block. Operator-injected args now precede the prompt-derived --command <X>, so under typical last-wins repeated-flag CLI semantics Spec Kit's command selection remains authoritative even if SPECIFY_OPENCODE_EXTRA_ARGS contains a stray --command. Added test_opencode_extra_args_cannot_clobber_prompt_derived_command to lock the ordering.

2. Test docstring. Rewrote the module docstring to describe the hook as living in IntegrationBase._apply_extra_args_env_var (not SkillsIntegration) and to acknowledge the file now covers Codex/Devin/Opencode/Copilot in addition to the SkillsIntegration stubs near the top.

Full suite: 2948 passed (+1), 35 skipped, no regressions.

AI disclosure: drafted with Claude Opus, human-reviewed.

[mnriem]

Please use SPECIFY_INTEGRATION__EXTRA_ARGS so we know it is targeting the integration subsystem. Good addition overall!

[Copilot]

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 2

[doquanghuy]

Pushed acab474 addressing both new findings:

1. Copilot dispatch_command bypass (the real bug). CopilotIntegration is the only integration that overrides dispatch_command — it builds cli_args inline rather than going through build_exec_args. The hook is now invoked in dispatch_command immediately after cli_args = ["copilot", "-p", prompt], between -p prompt and the canonical --agent / --yolo / --model / --output-format flags. Audit confirmed Copilot is the only override — Codex, Devin, Opencode all inherit IntegrationBase.dispatch_command which already delegates to build_exec_args, so they continue to honour their env vars through inheritance.

2. End-to-end test coverage. Added two tests that monkeypatch subprocess.run and assert the env-var args reach the executed argv:

• test_copilot_dispatch_command_includes_extra_args locks the bypass fix on the overridden path.
• test_codex_dispatch_command_includes_extra_args locks the inherited-base-dispatch path for Codex/Devin/Opencode by transitivity.

Full suite: 2950 passed (was 2948), 35 skipped, no regressions.

AI disclosure: drafted with Claude Opus, human-reviewed.

[doquanghuy]

@mnriem — done. Pushed 932cfb9 renaming the env var to SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS so the namespace is unambiguously scoped to the integration subsystem.

Updated everywhere it lives:

• Helper IntegrationBase._apply_extra_args_env_var env-name format and docstring.
• Inline comment in CopilotIntegration.dispatch_command.
• All monkeypatch.setenv(...) calls, docstrings, and the autouse fixture's scope filter in tests/integrations/test_extra_args.py.
• PR description (examples + reference table).

No behaviour change beyond the variable name. Full suite still 2950 passed, 35 skipped.

AI disclosure: drafted with Claude Opus, human-reviewed.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 1

[doquanghuy]

@mnriem — addressed the latest Copilot finding in 0ddac52, and rebased the branch onto current main (faf5129) to clear the conflict against _copilot_executable() that landed upstream.

The fix. IntegrationBase._apply_extra_args_env_var now wraps shlex.split in a try/except ValueError and re-raises a ValueError that:

1. Names the offending env var (SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS).
2. Echoes the invalid value with repr so quoting issues are visible.
3. Shows a concrete fix example ('--flag "value with spaces"').
4. Chains the original shlex exception via from exc so the underlying message is preserved.

A malformed env var now surfaces as a clear operator-facing error instead of a bare shlex traceback through workflow dispatch.

The rebase. Three of the existing commits touched the same line in src/specify_cli/integrations/copilot/__init__.py that #2640 (or whichever PR introduced _copilot_executable()) rewrote. Resolved by keeping _copilot_executable() everywhere and re-applying self._apply_extra_args_env_var(...) on the rewritten lines. No semantic change vs. the pre-rebase branch — same env-var hook, same placement between -p prompt and the canonical flags.

Test coverage. New test_malformed_quoting_raises_actionable_value_error locks the actionable-error path — feeds --flag "unterminated and asserts the message contains both the env-var name and the offending value. Full suite is now 3009 passed, 40 skipped (was 2950 / 35 pre-rebase — picked up upstream-main tests too), no regressions.

Branch is now MERGEABLE again and ready for another look whenever you have a moment.

AI disclosure: drafted with Claude Opus, human-reviewed.

[Copilot]

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 0 new

[mnriem]

Please address test errors

[doquanghuy]

@mnriem — Windows pytest failure fixed in e66a090.

Root cause. test_copilot_integration_honours_extra_args hardcoded "copilot" as the first expected argv token, but CopilotIntegration.build_exec_args calls _copilot_executable() which returns "copilot.cmd" on Windows (os.name == "nt"). The test passed on all three Ubuntu matrix entries and failed on all three Windows-latest entries (3.11 / 3.12 / 3.13) with:

E   AssertionError: assert ['copilot.cmd', '-p', 'p', '--allow-tool', ...]
                       == ['copilot',     '-p', 'p', '--allow-tool', ...]

Fix. Import _copilot_executable alongside CopilotIntegration and use it as the first expected argv token, matching the platform-aware pattern already used elsewhere in tests/test_workflows.py ("copilot.cmd" if os.name == "nt" else "copilot"). The companion test_copilot_dispatch_command_includes_extra_args was already platform-safe — it uses argv.index(...) lookups rather than full-argv equality.

Audit for similar issues on the sibling PRs. Checked #2663 and #2664 for the same Windows hazard pattern:

• feat(workflows): add continue_on_error step field for non-halting failures #2663: shell-step tests use run: "exit N" and run: "echo ..." (both valid in cmd.exe and bash); the two run: "true" instances are in validation-only tests that never actually shell out, so cmd.exe never sees them. No fix needed.
• feat(workflows): expose {{ context.run_id }} template variable #2664: only touches the template-namespace builder and tests use template variables / shell echo. No platform-specific code paths. No fix needed.

Full local suite: 3009 passed, 40 skipped. Re-pushed to origin/feat/integrations-extra-args.

AI disclosure: drafted with Claude Opus, human-reviewed.

[Copilot]

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 2

[mnriem]

Please address Copilot feedback

[doquanghuy]

@mnriem — addressed both new Copilot findings in 1ae8d52.

Why does Copilot keep finding things? Honest answer: each successive pass surfaces something the previous pass missed, not a deeper code-quality issue. The PR is incrementally tightening as the visible surface area expands (override integrations → dispatch_command bypass → malformed-quoting error → Windows portability → now executable-name coupling + base-class coverage). The underlying mechanism — single helper on IntegrationBase, applied between -p prompt and the canonical flags — has not changed since the original commit.

1. Codex executable name decoupled from self.key. CodexIntegration.build_exec_args hardcoded the executable name as the literal "codex" while the env-var lookup derived from self.key. The two should stay coupled — if self.key ever changes (rename, subclass), the argv would drift from the env-var scoping and silently break the env-var contract. DevinIntegration and OpencodeIntegration already use self.key here. Replaced the literal in Codex to match. Inline comment explains why so a future reader doesn't "simplify" it back to a literal.

2. Base-class coverage added. The test suite covered the SkillsIntegration mechanism (via stubs at the top) and all four build_exec_args overrides (Codex/Devin/Opencode/Copilot) end-to-end, but did not exercise MarkdownIntegration.build_exec_args or TomlIntegration.build_exec_args directly. Since most concrete integrations inherit those without overriding (Amp, Auggie, Generic, Bob, Forge, Iflow, Junie, Kilocode, KiroCli, Pi, Qodercli, Qwen, Roo, Shai, Windsurf → MarkdownIntegration; Gemini, Tabnine → TomlIntegration), the base wiring was the largest uncovered surface. Added two bare stubs (_MarkdownAgentStub, _TomlAgentStub) that subclass the bases without overriding, and two tests:

• test_markdown_integration_base_honours_extra_args — locks the base MarkdownIntegration.build_exec_args hook position (between -p prompt and --model / --output-format).
• test_toml_integration_base_honours_extra_args — locks the base TomlIntegration.build_exec_args hook position, including the TOML-specific -m (vs Markdown's --model) detail.

Full suite: 3011 passed (was 3009), 40 skipped, no regressions. Pushed to origin/feat/integrations-extra-args.

AI disclosure: drafted with Claude Opus, human-reviewed.