@protolabsai/proto 0.14.0

package/dist/bundled/qc-helper/docs/features/headless.md

@@ -0,0 +1,318 @@
+# Headless Mode
+
+Headless mode allows you to run Qwen Code programmatically from command line
+scripts and automation tools without any interactive UI. This is ideal for
+scripting, automation, CI/CD pipelines, and building AI-powered tools.
+
+## Overview
+
+The headless mode provides a headless interface to Qwen Code that:
+
+- Accepts prompts via command line arguments or stdin
+- Returns structured output (text or JSON)
+- Supports file redirection and piping
+- Enables automation and scripting workflows
+- Provides consistent exit codes for error handling
+- Can resume previous sessions scoped to the current project for multi-step automation
+
+## Basic Usage
+
+### Direct Prompts
+
+Use the `--prompt` (or `-p`) flag to run in headless mode:
+
+```bash
+qwen --prompt "What is machine learning?"
+```
+
+### Stdin Input
+
+Pipe input to Qwen Code from your terminal:
+
+```bash
+echo "Explain this code" | qwen
+```
+
+### Combining with File Input
+
+Read from files and process with Qwen Code:
+
+```bash
+cat README.md | qwen --prompt "Summarize this documentation"
+```
+
+### Resume Previous Sessions (Headless)
+
+Reuse conversation context from the current project in headless scripts:
+
+```bash
+# Continue the most recent session for this project and run a new prompt
+qwen --continue -p "Run the tests again and summarize failures"
+
+# Resume a specific session ID directly (no UI)
+qwen --resume 123e4567-e89b-12d3-a456-426614174000 -p "Apply the follow-up refactor"
+```
+
+> [!note]
+>
+> - Session data is project-scoped JSONL under `~/.qwen/projects/<sanitized-cwd>/chats`.
+> - Restores conversation history, tool outputs, and chat-compression checkpoints before sending the new prompt.
+
+## Customize the Main Session Prompt
+
+You can change the main session system prompt for a single CLI run without editing shared memory files.
+
+### Override the Built-in System Prompt
+
+Use `--system-prompt` to replace Qwen Code's built-in main-session prompt for the current run:
+
+```bash
+qwen -p "Review this patch" --system-prompt "You are a terse release reviewer. Report only blocking issues."
+```
+
+### Append Extra Instructions
+
+Use `--append-system-prompt` to keep the built-in prompt and add extra instructions for this run:
+
+```bash
+qwen -p "Review this patch" --append-system-prompt "Be terse and focus on concrete findings."
+```
+
+You can combine both flags when you want a custom base prompt plus an extra run-specific instruction:
+
+```bash
+qwen -p "Summarize this repository" \
+  --system-prompt "You are a migration planner." \
+  --append-system-prompt "Return exactly three bullets."
+```
+
+> [!note]
+>
+> - `--system-prompt` applies only to the current run's main session.
+> - Loaded memory and context files such as `QWEN.md` are still appended after `--system-prompt`.
+> - `--append-system-prompt` is applied after the built-in prompt and loaded memory, and can be used together with `--system-prompt`.
+
+## Output Formats
+
+Qwen Code supports multiple output formats for different use cases:
+
+### Text Output (Default)
+
+Standard human-readable output:
+
+```bash
+qwen -p "What is the capital of France?"
+```
+
+Response format:
+
+```
+The capital of France is Paris.
+```
+
+### JSON Output
+
+Returns structured data as a JSON array. All messages are buffered and output together when the session completes. This format is ideal for programmatic processing and automation scripts.
+
+The JSON output is an array of message objects. The output includes multiple message types: system messages (session initialization), assistant messages (AI responses), and result messages (execution summary).
+
+#### Example Usage
+
+```bash
+qwen -p "What is the capital of France?" --output-format json
+```
+
+Output (at end of execution):
+
+```json
+[
+  {
+    "type": "system",
+    "subtype": "session_start",
+    "uuid": "...",
+    "session_id": "...",
+    "model": "qwen3-coder-plus",
+    ...
+  },
+  {
+    "type": "assistant",
+    "uuid": "...",
+    "session_id": "...",
+    "message": {
+      "id": "...",
+      "type": "message",
+      "role": "assistant",
+      "model": "qwen3-coder-plus",
+      "content": [
+        {
+          "type": "text",
+          "text": "The capital of France is Paris."
+        }
+      ],
+      "usage": {...}
+    },
+    "parent_tool_use_id": null
+  },
+  {
+    "type": "result",
+    "subtype": "success",
+    "uuid": "...",
+    "session_id": "...",
+    "is_error": false,
+    "duration_ms": 1234,
+    "result": "The capital of France is Paris.",
+    "usage": {...}
+  }
+]
+```
+
+### Stream-JSON Output
+
+Stream-JSON format emits JSON messages immediately as they occur during execution, enabling real-time monitoring. This format uses line-delimited JSON where each message is a complete JSON object on a single line.
+
+```bash
+qwen -p "Explain TypeScript" --output-format stream-json
+```
+
+Output (streaming as events occur):
+
+```json
+{"type":"system","subtype":"session_start","uuid":"...","session_id":"..."}
+{"type":"assistant","uuid":"...","session_id":"...","message":{...}}
+{"type":"result","subtype":"success","uuid":"...","session_id":"..."}
+```
+
+When combined with `--include-partial-messages`, additional stream events are emitted in real-time (message_start, content_block_delta, etc.) for real-time UI updates.
+
+```bash
+qwen -p "Write a Python script" --output-format stream-json --include-partial-messages
+```
+
+### Input Format
+
+The `--input-format` parameter controls how Qwen Code consumes input from standard input:
+
+- **`text`** (default): Standard text input from stdin or command-line arguments
+- **`stream-json`**: JSON message protocol via stdin for bidirectional communication
+
+> **Note:** Stream-json input mode is currently under construction and is intended for SDK integration. It requires `--output-format stream-json` to be set.
+
+### File Redirection
+
+Save output to files or pipe to other commands:
+
+```bash
+# Save to file
+qwen -p "Explain Docker" > docker-explanation.txt
+qwen -p "Explain Docker" --output-format json > docker-explanation.json
+
+# Append to file
+qwen -p "Add more details" >> docker-explanation.txt
+
+# Pipe to other tools
+qwen -p "What is Kubernetes?" --output-format json | jq '.response'
+qwen -p "Explain microservices" | wc -w
+qwen -p "List programming languages" | grep -i "python"
+
+# Stream-JSON output for real-time processing
+qwen -p "Explain Docker" --output-format stream-json | jq '.type'
+qwen -p "Write code" --output-format stream-json --include-partial-messages | jq '.event.type'
+```
+
+## Configuration Options
+
+Key command-line options for headless usage:
+
+| Option                       | Description                                                              | Example                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `--prompt`, `-p`             | Run in headless mode                                                     | `qwen -p "query"`                                                        |
+| `--output-format`, `-o`      | Specify output format (text, json, stream-json)                          | `qwen -p "query" --output-format json`                                   |
+| `--input-format`             | Specify input format (text, stream-json)                                 | `qwen --input-format text --output-format stream-json`                   |
+| `--include-partial-messages` | Include partial messages in stream-json output                           | `qwen -p "query" --output-format stream-json --include-partial-messages` |
+| `--system-prompt`            | Override the main session system prompt for this run                     | `qwen -p "query" --system-prompt "You are a terse reviewer."`            |
+| `--append-system-prompt`     | Append extra instructions to the main session system prompt for this run | `qwen -p "query" --append-system-prompt "Focus on concrete findings."`   |
+| `--debug`, `-d`              | Enable debug mode                                                        | `qwen -p "query" --debug`                                                |
+| `--all-files`, `-a`          | Include all files in context                                             | `qwen -p "query" --all-files`                                            |
+| `--include-directories`      | Include additional directories                                           | `qwen -p "query" --include-directories src,docs`                         |
+| `--yolo`, `-y`               | Auto-approve all actions                                                 | `qwen -p "query" --yolo`                                                 |
+| `--approval-mode`            | Set approval mode                                                        | `qwen -p "query" --approval-mode auto_edit`                              |
+| `--continue`                 | Resume the most recent session for this project                          | `qwen --continue -p "Pick up where we left off"`                         |
+| `--resume [sessionId]`       | Resume a specific session (or choose interactively)                      | `qwen --resume 123e... -p "Finish the refactor"`                         |
+
+For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../configuration/settings).
+
+## Examples
+
+### Code review
+
+```bash
+cat src/auth.py | qwen -p "Review this authentication code for security issues" > security-review.txt
+```
+
+### Generate commit messages
+
+```bash
+result=$(git diff --cached | qwen -p "Write a concise commit message for these changes" --output-format json)
+echo "$result" | jq -r '.response'
+```
+
+### API documentation
+
+```bash
+result=$(cat api/routes.js | qwen -p "Generate OpenAPI spec for these routes" --output-format json)
+echo "$result" | jq -r '.response' > openapi.json
+```
+
+### Batch code analysis
+
+```bash
+for file in src/*.py; do
+    echo "Analyzing $file..."
+    result=$(cat "$file" | qwen -p "Find potential bugs and suggest improvements" --output-format json)
+    echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
+    echo "Completed analysis for $(basename "$file")" >> reports/progress.log
+done
+```
+
+### PR code review
+
+```bash
+result=$(git diff origin/main...HEAD | qwen -p "Review these changes for bugs, security issues, and code quality" --output-format json)
+echo "$result" | jq -r '.response' > pr-review.json
+```
+
+### Log analysis
+
+```bash
+grep "ERROR" /var/log/app.log | tail -20 | qwen -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt
+```
+
+### Release notes generation
+
+```bash
+result=$(git log --oneline v1.0.0..HEAD | qwen -p "Generate release notes from these commits" --output-format json)
+response=$(echo "$result" | jq -r '.response')
+echo "$response"
+echo "$response" >> CHANGELOG.md
+```
+
+### Model and tool usage tracking
+
+```bash
+result=$(qwen -p "Explain this database schema" --include-directories db --output-format json)
+total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
+models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
+tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
+tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
+echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
+echo "$result" | jq -r '.response' > schema-docs.md
+echo "Recent usage trends:"
+tail -5 usage.log
+```
+
+## Resources
+
+- [CLI Configuration](../configuration/settings#command-line-arguments) - Complete configuration guide
+- [Authentication](../configuration/settings#environment-variables-for-api-access) - Setup authentication
+- [Commands](../features/commands) - Interactive commands reference
+- [Tutorials](../quickstart) - Step-by-step automation guides

package/dist/bundled/qc-helper/docs/features/hooks.md

@@ -0,0 +1,343 @@
+# Hooks
+
+Run custom scripts at key points in the proto lifecycle — before tool calls, after edits, at session boundaries, and during agent team coordination.
+
+This page covers how to configure hooks, the available hook types and events, and the input/output contract for each event.
+
+## Configure a hook
+
+Hooks are defined in `.proto/settings.json` (project) or `~/.proto/settings.json` (global). Each hook attaches to an event name and optionally filters by a matcher pattern.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./scripts/check-bash-safety.sh",
+            "timeout": 10000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook types
+
+| Type      | Purpose                                                       | Key fields                         |
+| --------- | ------------------------------------------------------------- | ---------------------------------- |
+| `command` | Run a shell script. Event JSON on stdin, decisions on stdout. | `command`, `env`, `timeout`        |
+| `http`    | POST event JSON to a webhook URL.                             | `url`, `headers`, `allowedEnvVars` |
+| `prompt`  | Ask an LLM to make a judgment call.                           | `prompt`, `model`                  |
+
+#### Command hooks
+
+```json
+{
+  "type": "command",
+  "command": "/path/to/script.sh",
+  "timeout": 30000,
+  "env": { "CUSTOM_VAR": "value" }
+}
+```
+
+#### HTTP hooks
+
+```json
+{
+  "type": "http",
+  "url": "https://hooks.example.com/proto",
+  "headers": { "Authorization": "Bearer $API_TOKEN" },
+  "allowedEnvVars": ["API_TOKEN"]
+}
+```
+
+Only variables listed in `allowedEnvVars` are interpolated in `url` and `headers`. Other `$VAR` references resolve to empty string.
+
+#### Prompt hooks
+
+```json
+{
+  "type": "prompt",
+  "prompt": "Is this safe? Event: $ARGUMENTS. Respond with JSON: {\"decision\": \"allow\"} or {\"decision\": \"deny\", \"reason\": \"why\"}",
+  "model": "haiku"
+}
+```
+
+`$ARGUMENTS` is replaced with the event JSON. Model options: `haiku` (default), `sonnet`, `opus`.
+
+### Hook modifiers
+
+**`async`** — Run the hook in the background without blocking. Output and decisions are ignored.
+
+```json
+{ "type": "command", "command": "log-to-slack.sh", "async": true }
+```
+
+**`if`** — Fine-grained filter using permission-rule syntax. Only fires when tool arguments match the pattern. Avoids spawning a hook process for non-matching calls.
+
+```json
+{
+  "matcher": "bash",
+  "hooks": [
+    { "type": "command", "if": "Bash(git *)", "command": "check-git-policy.sh" }
+  ]
+}
+```
+
+Syntax: `ToolName(glob)` where the glob matches the tool's primary argument (`command` for Bash, `file_path` for Edit/Write, `pattern` for Grep). Valid only for tool events.
+
+## Events reference
+
+### Lifecycle events
+
+| Event              | When it fires                            | Can block?           |
+| ------------------ | ---------------------------------------- | -------------------- |
+| `SessionStart`     | Session begins or resumes                | No                   |
+| `SessionEnd`       | Session terminates                       | No                   |
+| `PreCompact`       | Before context compaction                | No                   |
+| `UserPromptSubmit` | User submits a prompt, before processing | Yes (exit 2)         |
+| `Stop`             | Before the model concludes its response  | Yes (exit 2 or JSON) |
+
+### Tool events
+
+| Event                | When it fires           | Can block? | Matcher target    |
+| -------------------- | ----------------------- | ---------- | ----------------- |
+| `PreToolUse`         | Before tool executes    | Yes        | Tool name (regex) |
+| `PostToolUse`        | After tool succeeds     | Limited    | Tool name (regex) |
+| `PostToolUseFailure` | After tool fails        | Limited    | Tool name (regex) |
+| `PermissionRequest`  | Permission dialog shown | Yes        | Tool name (regex) |
+
+### Agent events
+
+| Event           | When it fires     | Matcher target     |
+| --------------- | ----------------- | ------------------ |
+| `SubagentStart` | Subagent spawned  | Agent type (regex) |
+| `SubagentStop`  | Subagent finishes | Agent type (regex) |
+
+### Team events
+
+| Event           | When it fires                  | Can block?                  |
+| --------------- | ------------------------------ | --------------------------- |
+| `TeammateIdle`  | Background agent becomes idle  | Yes (exit 2 sends feedback) |
+| `TaskCreated`   | Task added to shared task list | No                          |
+| `TaskCompleted` | Task marked as completed       | No                          |
+
+### Notification events
+
+| Event          | When it fires     | Matcher target                                           |
+| -------------- | ----------------- | -------------------------------------------------------- |
+| `Notification` | Notification sent | Type: `permission_prompt`, `idle_prompt`, `auth_success` |
+
+## Input/output contract
+
+### Common input fields (all events)
+
+```json
+{
+  "session_id": "string",
+  "transcript_path": "string",
+  "cwd": "string",
+  "hook_event_name": "string",
+  "timestamp": "ISO 8601 string"
+}
+```
+
+### Exit codes (command hooks)
+
+| Exit code | Meaning            | Behavior                                          |
+| --------- | ------------------ | ------------------------------------------------- |
+| `0`       | Success            | Parse stdout as JSON for decisions                |
+| `1`       | Non-blocking error | Continue; stderr logged but not shown to model    |
+| `2`       | Blocking error     | Block the action; stderr fed to model as feedback |
+
+### JSON output format
+
+```json
+{
+  "continue": true,
+  "decision": "allow",
+  "reason": "explanation",
+  "hookSpecificOutput": {}
+}
+```
+
+### Event-specific fields
+
+#### PreToolUse
+
+**Additional input:** `permission_mode`, `tool_name`, `tool_input`, `tool_use_id`
+
+**Output:** `hookSpecificOutput.permissionDecision` (`allow` | `deny` | `ask`), `hookSpecificOutput.permissionDecisionReason`, `hookSpecificOutput.updatedInput`
+
+#### PostToolUse
+
+**Additional input:** `permission_mode`, `tool_name`, `tool_input`, `tool_response`, `tool_use_id`
+
+**Output:** `decision` (`allow` | `block`), `hookSpecificOutput.additionalContext`
+
+#### PostToolUseFailure
+
+**Additional input:** `permission_mode`, `tool_use_id`, `tool_name`, `tool_input`, `error`, `is_interrupt`
+
+#### UserPromptSubmit
+
+**Additional input:** `prompt`
+
+**Output:** `decision` (`allow` | `block`), `hookSpecificOutput.additionalContext`
+
+#### Stop
+
+**Additional input:** `stop_hook_active`, `last_assistant_message`
+
+**Output:** `decision` (`allow` | `block`), `reason`
+
+When `stop_hook_active` is `true`, the hook has already triggered a continuation. Exit early to prevent infinite loops.
+
+#### SessionStart
+
+**Additional input:** `permission_mode`, `source` (`startup` | `resume` | `clear` | `compact`), `model`, `agent_type`
+
+**Output:** `hookSpecificOutput.additionalContext` (injected into session context)
+
+#### SessionEnd
+
+**Additional input:** `reason` (`clear` | `logout` | `prompt_input_exit` | `other`)
+
+#### SubagentStart / SubagentStop
+
+**Additional input:** `permission_mode`, `agent_id`, `agent_type`
+
+SubagentStop also includes: `stop_hook_active`, `agent_transcript_path`, `last_assistant_message`
+
+#### PermissionRequest
+
+**Additional input:** `permission_mode`, `tool_name`, `tool_input`, `permission_suggestions`
+
+**Output:** `hookSpecificOutput.decision.behavior` (`allow` | `deny`), `hookSpecificOutput.decision.updatedInput`, `hookSpecificOutput.decision.message`
+
+#### PreCompact
+
+**Additional input:** `trigger` (`manual` | `auto`), `custom_instructions`
+
+#### TeammateIdle
+
+**Additional input:** `agent_id`, `agent_name`, `result_summary`, `success`
+
+#### TaskCreated
+
+**Additional input:** `task_id`, `task_title`, `task_description`, `created_by`
+
+#### TaskCompleted
+
+**Additional input:** `task_id`, `task_title`, `completed_by`, `output`
+
+## Matcher patterns
+
+Matchers are regex patterns that filter which occurrences of an event trigger a hook.
+
+| Event type             | Matches on      | Example                            |
+| ---------------------- | --------------- | ---------------------------------- |
+| Tool events            | Tool name       | `^bash$`, `read.*`, `(bash\|edit)` |
+| Subagent events        | Agent type      | `^Explore$`, `coordinator`         |
+| SessionStart           | Source          | `^(startup\|resume)$`              |
+| SessionEnd             | Reason          | `^clear$`                          |
+| Notification           | Type (exact)    | `permission_prompt`                |
+| PreCompact             | Trigger (exact) | `manual`                           |
+| UserPromptSubmit, Stop | Not supported   | Always fires                       |
+
+Empty string `""` or `"*"` matches all.
+
+## Execution model
+
+- Hooks run **in parallel** by default. Use `sequential: true` on a hook definition to enforce order.
+- When multiple hooks return conflicting decisions, the **most restrictive wins**: `deny` > `ask` > `allow`.
+- Project hooks require trusted folder status.
+- Default timeout: 60 seconds.
+- Max output: 1 MB per hook.
+
+## SDK hook callbacks
+
+When using the [TypeScript SDK](../reference/sdk-api.md), register hook callbacks directly in code instead of writing shell scripts or HTTP endpoints. The SDK registers callbacks with the CLI during initialization and invokes them when hook events fire.
+
+```typescript
+import { query, type HookCallback } from '@qwen-code/sdk';
+
+const auditLogger: HookCallback = async (input, toolUseId) => {
+  const data = input as { tool_name?: string };
+  console.log(`[audit] ${data.tool_name} (${toolUseId})`);
+  return {};
+};
+
+const securityGate: HookCallback = async (input) => {
+  const data = input as {
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+  };
+  if (data.tool_name === 'Bash') {
+    const cmd = String(data.tool_input?.command ?? '');
+    if (cmd.includes('rm -rf') || cmd.includes('sudo')) {
+      return { shouldSkip: true, message: 'Blocked: destructive command' };
+    }
+  }
+  return {};
+};
+
+const conversation = query({
+  prompt: 'Refactor the auth module',
+  options: {
+    hookCallbacks: {
+      PreToolUse: [auditLogger, securityGate],
+      PostToolUse: async (input) => {
+        const data = input as { tool_output?: string };
+        if (data.tool_output?.includes('FATAL')) {
+          return { shouldInterrupt: true, message: 'Fatal error detected' };
+        }
+        return {};
+      },
+    },
+  },
+});
+```
+
+### Callback return values
+
+| Field             | Type      | Effect                                                          |
+| ----------------- | --------- | --------------------------------------------------------------- |
+| `shouldSkip`      | `boolean` | Skip this tool call entirely. Only meaningful for `PreToolUse`. |
+| `shouldInterrupt` | `boolean` | Stop the agent immediately.                                     |
+| `suppressOutput`  | `boolean` | Suppress the tool's output from the conversation.               |
+| `message`         | `string`  | Feedback string sent to the agent.                              |
+
+Returning `{}` lets the tool proceed normally.
+
+### Supported SDK events
+
+| Event          | When it fires                   |
+| -------------- | ------------------------------- |
+| `PreToolUse`   | Before a tool executes          |
+| `PostToolUse`  | After a tool returns its result |
+| `Stop`         | When the agent is about to stop |
+| `Notification` | On agent notifications          |
+| `SubagentStop` | When a subagent finishes        |
+
+When multiple callbacks are registered for one event (as an array), they execute in order. The first `shouldSkip` or `shouldInterrupt` result short-circuits the rest.
+
+See the [SDK hooks examples](../../developers/examples/sdk-hooks.md) for more patterns.
+
+## Environment variables
+
+Command hooks inherit `process.env` plus:
+
+```
+GEMINI_PROJECT_DIR  — project root
+CLAUDE_PROJECT_DIR  — same (compatibility alias)
+QWEN_PROJECT_DIR    — same (compatibility alias)
+```
+
+Custom variables can be added via the `env` field on command hooks.