agentsys 5.1.0 → 5.2.0

package/plugins/consult/agents/consult-agent.md

@@ -1,222 +0,0 @@
----
-name: consult-agent
-description: "Execute cross-tool AI consultations via Task spawning. Use when agents or workflows need a second opinion from Gemini, Codex, Claude, OpenCode, or Copilot. Supports multi-instance parallel consultations (count > 1)."
-tools:
-  - Skill
-  - Bash(claude:*)
-  - Bash(gemini:*)
-  - Bash(codex:*)
-  - Bash(opencode:*)
-  - Bash(copilot:*)
-  - Bash(git:*)
-  - Bash(where.exe:*)
-  - Bash(which:*)
-  - Read
-  - Write
-model: sonnet
----
-
-# Consult Agent
-
-## Role
-
-You are the programmatic interface for cross-tool AI consultations. The consult plugin follows the standard Command -> Agent -> Skill pattern:
-
-- **Command** (`/consult`): User-facing entry point. Handles natural language parsing and interactive parameter selection. For single instance (count=1), invokes the consult skill directly. For multi-instance (count>1), spawns this agent.
-- **Agent** (this file): Programmatic entry point. Requires all parameters pre-resolved by the caller. Handles both single-instance (invoke skill) and multi-instance (parallel execution). Used by the command for multi-instance and by other agents/workflows via Task().
-- **Skill** (`consult`): Implementation source of truth. Provides provider configurations, model mappings, command templates, context packaging, and output parsing logic.
-
-Use this agent for:
-1. Multi-instance consultations (count > 1) dispatched by the /consult command
-2. Programmatic consultations from other agents or automated workflows
-
-## Why Sonnet Model
-
-Orchestration work: parse config, invoke skill, execute CLI command, parse output. No complex reasoning needed.
-
-## Workflow
-
-### 1. Parse Input
-
-Extract from prompt. ALL parameters MUST be pre-resolved by the caller (the /consult command or direct Task invocation). This agent runs as a subagent and cannot interact with the user.
-
-**Required** (caller must provide):
-- **tool**: Target tool (claude, gemini, codex, opencode, copilot)
-- **question**: The consultation question
-- **effort**: Thinking effort level (low, medium, high, max)
-
-**Optional**:
-- **model**: Specific model override (or null for auto from effort)
-- **context**: Context mode (diff, file, none) - default: none
-- **continueSession**: Session ID or true/false
-- **sessionFile**: Path to session state file
-- **count**: Number of parallel instances (1-5, default: 1)
-
-If any required parameter is missing, return an error as plain JSON:
-```json
-{"error": "Missing required parameter: [param]. The caller must resolve all parameters before spawning this agent."}
-```
-
-### 2. Route: Single vs Multi-Instance
-
-If both `continueSession` is set and `count > 1`, return:
-```json
-{"error": "Cannot use --continue with count > 1. Session resume applies to a single tool session."}
-```
-
-Validate count: if provided, must be 1-5. If out of range, return `{"error": "Instance count must be 1-5. Got: [count]"}`.
-
-If `count` is 1 (or not provided), follow the **Single Instance** path (Step 3).
-If `count` is 2-5, follow the **Multi-Instance** path (Step 4).
-
-### 3. Single Instance (count=1)
-
-#### 3a. Invoke Consult Skill (MUST)
-
-You MUST invoke the `consult` skill using the Skill tool. Pass all parsed arguments. The skill is the authoritative source for provider configurations, model mappings, command building, context packaging, session loading, and output parsing. Do not bypass the skill.
-
-```
-Skill: consult
-Args: [question] --tool=[tool] --effort=[effort] [--model=[model]] [--context=[context]] [--continue=[session]]
-
-Example: "Review this function" --tool=claude --effort=high --model=opus
-```
-
-#### 3b. Execute Command
-
-Run the CLI command returned by the skill via Bash with a 120-second timeout.
-
-#### 3c. Parse and Return Result
-
-Parse the response using the method specified by the skill for the target tool, then format and display the result as human-friendly text:
-
-```
-Tool: {tool}, Model: {model}, Effort: {effort}, Duration: {duration_ms}ms.
-
-The results of the consultation are:
-{response}
-```
-
-Set `continuable: true` for Claude, Gemini, Codex, and OpenCode (tools with session resume support). Only Copilot is non-continuable. Each tool uses a different resume mechanism: Claude/Gemini use `--resume`, Codex uses `codex exec resume`, OpenCode uses `--session`/`--continue`.
-
-#### 3d. Save Session State
-
-Write session state to the sessionFile path provided by the command for continuity.
-
-### 4. Multi-Instance (count > 1)
-
-When count > 1, execute N parallel consultations with the same tool and parameters.
-
-#### 4a. Invoke Consult Skill Once
-
-Invoke the `consult` skill once to get the resolved command template and provider configuration. This gives you the exact CLI command to run for this tool/model/effort combination. Do NOT execute the command from the skill response yet.
-
-#### 4b. Write Indexed Temp Files
-
-Write the question to N indexed temp files using the Write tool:
-- `{AI_STATE_DIR}/consult/question-1.tmp`
-- `{AI_STATE_DIR}/consult/question-2.tmp`
-- ... through `question-{count}.tmp`
-
-Platform state directory:
-- Claude Code: `.claude/`
-- OpenCode: `.opencode/`
-- Codex CLI: `.codex/`
-
-All temp files contain the same question text (with context prepended if applicable).
-
-#### 4c. Execute N Commands in Parallel
-
-Run N Bash commands **in parallel** (multiple Bash tool calls in a single message). Each command uses the template from Step 4a but points to its own indexed temp file. Set 120-second timeout on each.
-
-Example for 3 parallel Codex calls:
-```
-Bash: codex exec "$(cat "{AI_STATE_DIR}/consult/question-1.tmp")" --json -m "gpt-5.3-codex" -c model_reasoning_effort="high"
-Bash: codex exec "$(cat "{AI_STATE_DIR}/consult/question-2.tmp")" --json -m "gpt-5.3-codex" -c model_reasoning_effort="high"
-Bash: codex exec "$(cat "{AI_STATE_DIR}/consult/question-3.tmp")" --json -m "gpt-5.3-codex" -c model_reasoning_effort="high"
-```
-
-#### 4d. Parse and Format Results
-
-Parse each response using the skill's output parsing rules for the target tool. Format as numbered responses:
-
-```
-# Multi-Consultation Results
-
-Tool: {tool}, Model: {model}, Effort: {effort}, Instances: {count}
-
----
-
-## Response 1 (Duration: {duration_ms}ms)
-
-{response_1}
-
----
-
-## Response 2 (Duration: {duration_ms}ms)
-
-{response_2}
-
----
-
-[... for each instance ...]
-
----
-
-## Synthesis
-
-Key agreement points:
-- [Common themes across responses]
-
-Key differences:
-- [Where responses diverge]
-```
-
-If some instances failed but others succeeded, show the successful responses and note failures:
-`[WARN] Instance {N} failed: {error}. Showing {M} of {count} responses.`
-
-#### 4e. Clean Up and Save State
-
-1. Delete all indexed temp files (`question-1.tmp` through `question-{count}.tmp`)
-2. Save multi-session state to `{AI_STATE_DIR}/consult/last-multi-session.json`:
-
-```json
-{
-  "tool": "codex",
-  "model": "gpt-5.3-codex",
-  "effort": "high",
-  "count": 3,
-  "timestamp": "{ISO 8601 timestamp of execution}",
-  "question": "original question text",
-  "sessions": [
-    {"session_id": "abc-123", "continuable": true},
-    {"session_id": "def-456", "continuable": true},
-    {"session_id": "ghi-789", "continuable": true}
-  ]
-}
-```
-
-3. Also save the first session to `{AI_STATE_DIR}/consult/last-session.json` (standard format) so `--continue` works.
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Tool not installed | Return error with install command (see skill for install instructions) |
-| Command timeout (>120s) | Kill process, return partial output. Do NOT retry automatically. |
-| JSON parse failure | Return raw text as response |
-| Session file missing | Start fresh (ignore --continue) |
-| Empty response | Return error suggesting retry with higher effort |
-
-## Output Sanitization
-
-Apply the redaction patterns from the consult skill (`plugins/consult/skills/consult/SKILL.md`, Output Sanitization section). The skill is the canonical source for all redaction patterns.
-
-## Critical Constraints
-
-- NEVER expose API keys in commands or output. Keys in logs can be captured and exploited.
-- NEVER run commands with `--dangerously-skip-permissions` or `bypassPermissions`. These bypass safety checks.
-- MUST invoke the `consult` skill before executing any command. The skill is the single source of truth for provider configs.
-- MUST set a 120-second timeout on Bash execution. Prevents hanging processes and resource exhaustion.
-- MUST use safe-mode defaults for all tool invocations (skill defines per-provider flags). Prevents unintended writes or destructive actions.
-- MUST sanitize tool output before returning. Consulted tools may echo environment variables or API keys in their response.

package/plugins/consult/commands/consult.md

@@ -1,325 +0,0 @@
----
-name: consult
-description: Consult another AI CLI tool for a second opinion. Use when you want to cross-check ideas, get alternative approaches, or validate decisions with Gemini, Codex, Claude, OpenCode, or Copilot.
-codex-description: 'Use when user asks to "consult gemini", "ask codex", "get second opinion", "cross-check with claude", "consult another AI", "ask opencode", "copilot opinion", "ask 3 codex", "multi-consult". Queries another AI CLI tool and returns the response.'
-argument-hint: "[natural language or flags] [--tool] [--effort] [--model] [--context] [--continue] [--count=N]"
-allowed-tools: Skill, Task, Bash(git:*), Bash(claude:*), Bash(gemini:*), Bash(codex:*), Bash(opencode:*), Bash(copilot:*), Bash(where.exe:*), Bash(which:*), Read, Write, AskUserQuestion
----
-
-# /consult - Cross-Tool AI Consultation
-
-You are executing the /consult command. Your job is to parse the user's request (natural language or flags), resolve missing parameters interactively, and execute the consultation.
-
-## Constraints
-
-- NEVER expose API keys in commands or output
-- NEVER run with permission-bypassing flags (`--dangerously-skip-permissions`, `bypassPermissions`)
-- MUST use safe-mode defaults (`--allowedTools "Read,Glob,Grep"` for Claude, `-c model_reasoning_effort` for Codex)
-- MUST enforce 120s timeout on all tool executions
-- MUST validate tool names against allow-list: gemini, codex, claude, opencode, copilot (reject all others)
-- MUST validate `--context=file=PATH` is within the project directory (reject absolute paths outside cwd)
-- MUST quote all user-provided values in shell commands to prevent injection
-- NEVER execute tools the user has not explicitly requested
-
-## Execution
-
-### Phase 1: Parse Input (Flags + Natural Language)
-
-Parse `$ARGUMENTS` using both explicit flags and natural language extraction. Flags always take priority over NLP when both provide the same parameter.
-
-#### Step 1a: Extract explicit flags
-
-Look for and remove these flags from `$ARGUMENTS`:
-
-1. `--tool=VALUE` or `--tool VALUE` where VALUE is one of: gemini, codex, claude, opencode, copilot
-2. `--effort=VALUE` or `--effort VALUE` where VALUE is one of: low, medium, high, max
-3. `--model=VALUE` or `--model VALUE` (any string, including quoted)
-4. `--context=VALUE` where VALUE is: diff, file=PATH, or none
-5. `--continue` (optionally `--continue=SESSION_ID`)
-6. `--count=N` where N is 1-5
-
-Remove all matched flags and their values from `$ARGUMENTS`.
-
-#### Step 1b: Natural language extraction (on remaining text)
-
-After removing flags, parse the remaining text for these patterns:
-
-**Tool extraction** (case-insensitive):
-- "with {tool}" (e.g., "with codex") -> tool
-- "ask {tool}" (e.g., "ask gemini") -> tool
-- "consult {tool}" -> tool
-- "{tool} about" (e.g., "codex about") -> tool
-- Tool names: claude, gemini, codex, opencode, copilot
-
-**Count extraction**:
-- "ask {N} {tool}" (e.g., "ask 3 codex") -> count=N, tool
-- "{N} {tool}" (e.g., "3 codex") -> count=N, tool
-- "{N} instances" -> count=N
-- "few instances" / "multiple" / "several" -> count=ambiguous (ask user in Phase 2)
-
-**Count validation**: After extracting count (from flags or NLP), validate: 1 <= count <= 5. If count < 1 or count > 5, show `[ERROR] Instance count must be 1-5. Got: {count}` and stop.
-
-**Effort extraction**:
-- "quick" / "fast" / "brief" -> effort=low
-- "thorough" / "deep" / "carefully" / "detailed" -> effort=high
-- "maximum" / "max effort" / "exhaustive" -> effort=max
-
-**Question extraction**:
-- Text after "about" is the question (e.g., "with codex about my auth approach" -> question="my auth approach")
-- If no "about" pattern, everything remaining after removing tool/count/effort markers is the question
-
-**Precedence rule**: Flags from Step 1a always override NLP from Step 1b.
-
-If no question text and no `--continue` flag found after both steps:
-```
-[ERROR] Usage: /consult "your question" or /consult with gemini about your question
-```
-
-### Phase 2: Interactive Parameter Resolution
-
-MUST resolve ALL missing parameters interactively. ONLY skip this phase if ALL required params (tool, effort, model) are resolved AND either a question exists or --continue is present. Do NOT silently default any parameter.
-
-#### Step 2a: Handle --continue
-
-**Note:** `--continue` and `--count > 1` are mutually exclusive. Session resume applies to a single tool session. If both are present, show `[ERROR] Cannot use --continue with --count > 1. Use --continue for single session resume.` and stop.
-
-If `--continue` is present:
-1. Read the session file at `{AI_STATE_DIR}/consult/last-session.json`
-
-   Platform state directory:
-   - Claude Code: `.claude/`
-   - OpenCode: `.opencode/`
-   - Codex CLI: `.codex/`
-2. If the file exists, restore the saved tool, session_id, and model from it
-3. If the file does not exist, show `[WARN] No previous session found` and proceed as a fresh consultation
-
-#### Step 2b: Detect installed tools
-
-Run all 5 checks **in parallel** via Bash:
-
-- `where.exe <tool> 2>nul && echo FOUND || echo NOTFOUND` (Windows)
-- `which <tool> 2>/dev/null && echo FOUND || echo NOTFOUND` (Unix)
-
-Check for: claude, gemini, codex, opencode, copilot.
-
-If zero tools are installed: `[ERROR] No AI CLI tools found. Install at least one: npm i -g @anthropic-ai/claude-code, npm i -g @openai/codex, npm i -g opencode-ai`
-
-#### Step 2c: Batch selection for missing params
-
-Use a SINGLE AskUserQuestion call to ask all missing parameters at once. Include ONLY questions for parameters NOT already resolved from Phase 1:
-
-```
-AskUserQuestion:
-  questions:
-    - header: "AI Tool"                          # SKIP if tool resolved
-      question: "Which AI tool should I consult?"
-      multiSelect: false
-      options (only if installed):
-        - label: "Claude"       description: "Deep code reasoning"
-        - label: "Gemini"       description: "Fast multimodal analysis"
-        - label: "Codex"        description: "Agentic coding"
-        - label: "OpenCode"     description: "Flexible model choice"
-        - label: "Copilot"      description: "GitHub-integrated AI"
-
-    - header: "Effort"                           # SKIP if effort resolved
-      question: "What thinking effort level?"
-      multiSelect: false
-      options:
-        - label: "Medium (Recommended)"  description: "Balanced speed and quality"
-        - label: "Low"                   description: "Fast, minimal reasoning"
-        - label: "High"                  description: "Thorough analysis"
-        - label: "Max"                   description: "Maximum reasoning depth"
-
-    - header: "Instances"                        # SKIP if count resolved or not hinted
-      question: "How many parallel consultations?"
-      multiSelect: false
-      options:
-        - label: "1 (Single)"             description: "Standard single consultation"
-        - label: "2 (Compare)"            description: "Two responses to compare"
-        - label: "3 (Panel)"              description: "Three perspectives"
-        - label: "5 (Full spread)"        description: "Five diverse perspectives"
-```
-
-ONLY show the Instances question if:
-- The user explicitly mentioned multiple instances (e.g., "few", "multiple", "several")
-- The count was set but ambiguous
-Do NOT show Instances question for simple single-tool requests. Default count=1 silently when no multi-instance intent detected.
-
-Map tool choice to lowercase: "Claude" -> "claude", "Codex" -> "codex", etc.
-Map effort choice: "Medium (Recommended)" -> "medium", "Low" -> "low", etc.
-Map count choice: "1 (Single)" -> 1, "2 (Compare)" -> 2, "3 (Panel)" -> 3.
-
-#### Step 2d: Model selection (MUST ask if no --model)
-
-After tool is resolved, present a model picker with options specific to the selected tool. The user can always type a custom model name via the "Other" option.
-
-**For Claude:**
-```
-AskUserQuestion:
-  questions:
-    - header: "Model"
-      question: "Which Claude model?"
-      multiSelect: false
-      options:
-        - label: "sonnet (Recommended)"  description: "Sonnet 4.5 - balanced speed and intelligence"
-        - label: "opus"                  description: "Opus 4.6 - most capable, adaptive thinking"
-        - label: "haiku"                 description: "Haiku 4.5 - fastest, lightweight"
-```
-
-**For Gemini:**
-```
-AskUserQuestion:
-  questions:
-    - header: "Model"
-      question: "Which Gemini model?"
-      multiSelect: false
-      options:
-        - label: "gemini-3-pro"          description: "Most capable, strong reasoning"
-        - label: "gemini-3-flash"        description: "Fast, 78% SWE-bench"
-        - label: "gemini-2.5-pro"        description: "Previous gen pro model"
-        - label: "gemini-2.5-flash"      description: "Previous gen flash model"
-```
-
-**For Codex:**
-```
-AskUserQuestion:
-  questions:
-    - header: "Model"
-      question: "Which Codex model?"
-      multiSelect: false
-      options:
-        - label: "gpt-5.3-codex"        description: "Latest, most capable coding model"
-        - label: "gpt-5.2-codex"        description: "Strong coding model"
-        - label: "gpt-5.2"              description: "General purpose GPT-5.2"
-        - label: "gpt-5.3-codex-spark"   description: "Cost-effective, 4x more usage"
-```
-
-**For OpenCode:**
-```
-AskUserQuestion:
-  questions:
-    - header: "Model"
-      question: "Which model? (type via Other for paid: anthropic/claude-opus-4-6, openai/gpt-5.3-codex)"
-      multiSelect: false
-      options:
-        - label: "opencode/big-pickle"             description: "Free - Zen stealth model, 200K context"
-        - label: "opencode/minimax-m2.1-free"      description: "Free - 230B MoE, strong multilingual coding"
-        - label: "opencode/kimi-k2.5-free"         description: "Free - 1T multimodal, strong coding and agentic"
-        - label: "opencode/trinity-large-preview"  description: "Free - 400B sparse MoE by Arcee AI, 512K context"
-```
-
-**For Copilot:**
-```
-AskUserQuestion:
-  questions:
-    - header: "Model"
-      question: "Which Copilot model?"
-      multiSelect: false
-      options:
-        - label: "claude-sonnet-4-5"        description: "Default Copilot model"
-        - label: "claude-opus-4-6"          description: "Most capable Claude model"
-        - label: "gpt-5.3-codex"            description: "OpenAI GPT-5.3 Codex"
-        - label: "gemini-3-pro"             description: "Google Gemini 3 Pro"
-```
-
-Map the user's choice to the model string (strip " (Recommended)" suffix if present).
-
-IMPORTANT: Do NOT skip model selection. Do NOT silently use a default model. If --model was not explicitly provided, you MUST present this picker.
-
-### Phase 3: Execute Consultation
-
-With all parameters resolved (tool, effort, model, question, count, and optionally context/continue):
-
-#### Single instance (count=1, the default)
-
-Invoke the `consult` skill directly using the Skill tool:
-
-```
-Skill: consult
-Args: "[question]" --tool=[tool] --effort=[effort] --model=[model] [--context=[context]] [--continue=[session_id]]
-
-Example: "Is this the right approach?" --tool=gemini --effort=high --model=gemini-3-pro
-```
-
-The skill handles the full consultation lifecycle: model resolution, command building, context packaging, execution with 120s timeout, and returns a plain JSON result.
-
-#### Multi-instance (count > 1)
-
-Spawn the `consult:consult-agent` via the Task tool with all resolved parameters:
-
-```
-Task:
-  subagent_type: "consult:consult-agent"
-  prompt: |
-    Execute a multi-instance consultation with these pre-resolved parameters:
-    - tool: [tool]
-    - model: [model]
-    - effort: [effort]
-    - question: [question]
-    - count: [count]
-    - context: [context or none]
-
-    Run [count] parallel consultations with the same tool and parameters.
-    Return all responses formatted with numbered headers and a brief synthesis.
-```
-
-The agent handles parallel execution, temp file management, result parsing, and synthesis.
-
-### Phase 4: Present Results
-
-#### Single instance
-
-Parse the skill's plain JSON output and display:
-
-```
-Tool: {tool}, Model: {model}, Effort: {effort}, Duration: {duration_ms}ms.
-
-The results of the consultation are:
-{response}
-```
-
-For continuable tools (Claude, Gemini, Codex, OpenCode), display: `Session: {session_id} - use /consult --continue to resume`
-
-Save session state to `{AI_STATE_DIR}/consult/last-session.json`.
-
-#### Multi-instance
-
-Display the agent's formatted output directly. The agent returns numbered responses with a synthesis section.
-
-On failure: `[ERROR] Consultation Failed: {specific error message}`
-
-## Error Handling
-
-| Error | Output |
-|-------|--------|
-| No question provided | `[ERROR] Usage: /consult "your question" or /consult with gemini about your question` |
-| Tool not installed | `[ERROR] {tool} is not installed. Install with: {install command from skill}` |
-| Tool execution fails | `[ERROR] {tool} failed: {error}. Try a different tool with --tool=[other]` |
-| Timeout (>120s) | `[ERROR] {tool} timed out after 120s. Try --effort=low for faster response` |
-| No tools available | `[ERROR] No AI CLI tools found. Install: npm i -g @anthropic-ai/claude-code` |
-| Session not found | `[WARN] No previous session found. Starting fresh consultation.` |
-| API key missing | `[ERROR] {tool} requires API key. Set {env var} (see skill for details)` |
-| Count out of range | `[ERROR] Instance count must be 1-5. Got: {count}` |
-| Multi-instance partial failure | Show successful responses, note failures |
-
-## Example Usage
-
-```bash
-# Natural language (NLP parsing)
-/consult with codex about my auth approach
-/consult ask 3 codex about this design
-/consult gemini should I use redis or postgres
-/consult thoroughly ask claude about error handling
-/consult codex few instances about performance
-
-# Explicit flags (backward compatible)
-/consult "Is this the right approach?" --tool=gemini --effort=high
-/consult "Review this function" --tool=codex --count=3
-/consult "Suggest improvements" --tool=opencode --model=github-copilot/claude-opus-4-6
-/consult --continue
-/consult "Explain this error" --context=diff --tool=gemini
-/consult "Review this file" --context=file=src/index.js --tool=claude
-
-# Mixed (flags + natural language)
-/consult with gemini --effort=max about database schema design
-```