Skip to content

docs(site): document signal tool Stage 3 exit semantics #876

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(site): document signal tool Stage 3 exit semantics #876

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
21 changes: 20 additions & 1 deletion site/src/content/docs/reference/safe-outputs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,21 @@ When `workspace: root` and multiple repositories are checked out, agents can cre
```
The `repository` value must be `"self"`, an alias from the `checkout:` list in the front matter, the full Azure DevOps repository name (e.g. `project/repo`), or the bare repository name (case-insensitive, e.g. `sdk-FtdiDeviceControl` for an entry whose ADO name is `4x4/sdk-FtdiDeviceControl`).

## Signal Tools

The four *signal tools* communicate agent outcomes without creating external ADO artifacts (no PR, no wiki page, no branch). Choose the right one based on what happened and how urgent it is:

| Tool | Stage 3 result | ADO work item filed? |
|------|---------------|----------------------|
| `noop` | ✅ Succeeded (or ⚠️ Succeeded with Issues) | **Yes** — create-or-append on every run |
| `missing-data` | ✅ Succeeded | No |
| `missing-tool` | ✅ Succeeded (or ⚠️ Succeeded with Issues) | **Yes** — create-or-append on every run |
| `report-incomplete` | ❌ **Failed** | No |

**"Succeeded with Issues"** (exit code 2) occurs when `noop` or `missing-tool` need to file a work item but cannot reach ADO — for example, when no write service connection is configured. The pipeline build shows as "Succeeded with Issues" rather than "Failed" so a missing credential doesn't block visibility.

**`report-incomplete` marks the pipeline run as Failed** (exit code 1). This is intentional: it signals that the agent could not accomplish the assigned task and an operator must investigate. Use it when the agent's primary goal is unachievable, not just when information is missing.

### noop
Reports that no action was needed. Use this to provide visibility when analysis is complete but no changes or outputs are required.

Expand Down Expand Up @@ -231,6 +246,8 @@ Reports that data or information needed to complete the task is not available.
- `reason` - Why this data is required
- `context` - Optional additional context about the missing information

Stage 3 logs the report and succeeds. Unlike `noop` and `missing-tool`, `missing-data` does **not** file an ADO work item and has no front-matter configuration options.

### missing-tool
Reports that a tool or capability needed to complete the task is not available.

Expand All @@ -257,12 +274,14 @@ safe-outputs:
```

### report-incomplete
Reports that a task could not be completed.
Reports that a task could not be completed. **Stage 3 fails** when this tool fires (exit code 1, ADO build shows "Failed"). Use this when the agent's primary goal is unachievable, not when information is merely missing.

**Agent parameters:**
- `reason` - Why the task could not be completed (required, at least 10 characters)
- `context` - Optional additional context about what was attempted

There are no front-matter configuration options for this tool.

### add-pr-comment
Adds a new comment thread to a pull request.

Expand Down