# Agent Access tools

Sessions can read; actions need your grant. [Connect an outside agent](/docs/agent-access-connect) explains session setup.

## How reads work

Reads return evidence and truncation metadata, with no model calls or saved recommendations.

- **Scan first, then fetch.** Each `scan` tool returns compact rows. Use `getTasks` (up to 20 ids per call) or a context or detail tool to fetch full records.
- **Rows come newest first,** except `listTurns`, which lists oldest first. When more rows exist the answer includes an opaque `nextCursor`. Pass it back unchanged. A malformed cursor is refused, not restarted from the top.
- **Page size.** `limit` defaults to 25, or 50 for `scanApprovals` and `getTaskHistory`, and is capped at 100. A limit outside the range is clamped, not refused. `listTurns` refuses a limit over 100 instead. `scanTaskRuns`, `scanTaskApprovals`, `scanTaskEvents` and `scanVerdicts` refuse a `limit` over 50, and `scanVerdicts` a window over 72 hours. Each refusal names the cap. These reads and `getRun` share 40 calls an hour per session. An unknown or foreign id is an empty page.
- **Origin.** The context tools can return an `origin` section: who created a task, when its story, acceptance criteria and plan were written or approved, and how far the code has moved.
- **Ask the guide for words.** `readGuide` turns what the user sees into the name to call, and back.

## Arguments are strict

Missing or undeclared arguments, wrong types and values outside closed lists are refused with the argument named. Nothing is coerced to a default, so a misspelled filter never silently returns an unfiltered set.

## Request ids and the audit trail

Every action needs a `requestId`; reuse never runs it twice. Each attempt appears in the audit trail with one outcome:

- **`denied`**: the call was not admitted: the grant did not cover it, the `requestId` was missing, a required reason was unusable, or an argument did not validate. A denied call does not spend its `requestId`.
- **`failed`**: the call was admitted, but the action refused it (an idea that already left Ideas, say) or failed. The reason is recorded.
- **`allowed`**: the action was carried out.

`createIdea`, `setTaskPriority`, `editUnstartedIdea`, `proposeTaskChange`, `pullNextSprint`, `dismissProviderWarning` and `triggerBoardPass` replay saved outcomes for the same id and normalized arguments: creation never files twice, edits preserve later text, proposals return the original review, rollover and warning dismissal preserve later work and holds, and board starts return the original run. Changed arguments conflict. `_meta.operation` carries id, state, replay flag and any `work` reference. Assistant receipts identify the run, and Timeline and self-audit show its work. Grants gate every retry. Saved refusals stay final; use a new id after fixing the cause. Historical ids stay reserved and may refuse replay when no result is kept.

Operator storage controls add seven days once per request or make files unavailable before cleanup. Expiry preserves running work. Inspect unconfirmed cleanup's original request; unavailable files cannot resume.

`reportFeedback` returns the first report when its `requestId` repeats, even if later text differs. New reports carry `_meta.operation`; historical ones replay without a receipt.

## Read tools

| Tool | What it returns |
| --- | --- |
| `scanTasks` | Compact task rows, filtered by text, steps, priorities and times, with `excludeTerminal` to hide finished work. |
| `getTasks` | Full task records for up to 20 ids, in order. Missing or foreign ids come back unresolved. |
| `getRelationships` | One task's neighborhood: its dependencies in both directions, parent and children, and where it came from or what it spawned. Each dependency says what it gates and how far the upstream task must get to clear it. |
| `getWorkspaceOverview` | Task counts by lifecycle state and priority, open approvals and live work, for inspecting flow and bottlenecks. |
| `getTaskThroughput` | A rolling, source-by-source comparison of tasks created and closed, in seven-day buckets, with the current state of each source's creation cohort. It breaks generated Breakdown and follow-up work down by origin step and root source. It defaults to 60 days, accepts up to 90, and can end at a supplied Unix-millisecond time. |
| `getFailurePatterns` | Recent failure asks and failed runs, including runs that belong to no task, for finding recurring patterns. |
| `getImprovementSignals` | Failure and guidance-gap evidence for spotting recurring trip-ups. |
| `scanGuidanceGaps` | The workspace's guidance-gap ledger, by status, originating task, seat and dates. |
| `scanFeedback` | Factory problems reported in the workspace, by status or task. Reported text is quoted evidence from whoever wrote it. |
| `scanApprovals` | The open approval inbox as compact rows without proposal payloads, filtered by task, case, whether it blocks work, and request time. |
| `getApproval` | One approval: its category, the decisions allowed, whether this session holds that category, and the fingerprint a response must echo. |
| `getApprovalContext` | Selected full evidence sections for one approval. |
| `getTaskContext` | Selected full evidence sections for one task, including `origin`. Relationship children reflect current parent membership; `getRelationships` reports creation provenance. |
| `getTaskHistory` | One task's audit trail: step changes with their cause, open and answered approvals, and plan metadata. Events are paged; free text is bounded and redacted. |
| `scanRuns` | Compact runs without verdicts or transcripts, filtered by task, liveness, status, phase and time. Verdicts come from `scanTaskRuns`, `getRun` or `scanVerdicts`. |
| `scanTaskRuns` | One task's runs, newest first, with phase, trigger, status, times, verdict tag and verdict body. A body over 8 KiB is cut and marked `verdictTrimmed: true`. |
| `getRun` | One run by id, as a one-row page in the `scanTaskRuns` shape. |
| `scanTaskApprovals` | One task's open and answered approvals with the answer, up to 8 KiB. Needs `approvals.read`. |
| `scanTaskEvents` | One task's history events in the `getTaskHistory` shape. Needs `workspace.read`. |
| `scanVerdicts` | Verdicts of task runs that ended in a window of up to 72 hours (24 by default), by phase and verdict tag. Workspace passes are not included. |
| `getTurnExcerpt` | One bounded, redacted excerpt of a turn transcript. |
| `listTurns` | The turns of one run, or of one task's runs, oldest first: phase, timing, model, effort, account, tokens in and out, cost (absent if none was recorded) and outcome. Pages hold up to 100. No prompt or transcript text; `getTurnExcerpt` reads one transcript. |
| `getSafeSettings` | Workspace settings without credentials or connection secrets. |
| `showPreview` | A render-only preview intent for this workspace. An optional path must name a renderable page; Settings and account/admin paths are refused. |
| `readGuide` | The ampm product guide, one piece at a time: the section index, one section, or one glossary term pairing the words on screen with the tool, field or key an agent uses. A response stays under 32 KiB; a longer section is cut at a line with a note. It reads no workspace data. |

## Action tools

Each requires its grant and a `requestId`. Current limits are checked on every call. [How permissions work](/docs/agent-access-permissions) explains the check.

| Tool | Grant label | What it does and what it refuses |
| --- | --- | --- |
| `createIdea` | Create ideas | Creates an item in Ideas, optionally under an existing parent in the same workspace; a parent that does not resolve refuses the call. A parent ampm closed itself reopens to take it. A parent a person closed files the item under the nearest open ancestor or at the top level, and the result says so. Reparenting is a task change. The result warns when the stored priority differs from the one requested. |
| `editUnstartedIdea` | Edit unstarted ideas | Edits the title or body of an item still in Ideas, against the revision the agent last read; refused once it leaves Ideas. A concurrent edit returns a revision conflict. |
| `proposeTaskChange` | Propose task changes | Files a change to a task's meaning for specialist and human review; it never applies it. A parent change naming a closed task is refused. |
| `setTaskPriority` | Set task priority | Changes a task's priority. Only you can grant P0, so a P0 request comes back with the lower stored priority and a warning; the agent should report the stored priority. A refused immediate start leaves the previous priority intact. |
| `promoteIdea` | Promote ideas | Moves one named idea into intake, with an optional recorded reason. |
| `scheduleFutureTask` | Schedule future tasks | Places a task in the backlog, Soon or Next, with a required reason; never in the current sprint or a later stage. |
| `triggerBoardPass` | Start board passes | Starts one of four board passes: `groom`, `plan` (sprint planning), `promote` or `groom-ideas`. If it cannot start, the answer says `started: false` with the reason. Admission records a run before replying; every proposal still arrives as an ordinary approval. |
| `pullNextSprint` | Pull the next sprint | Advances the planned sprint window by one: every Next task enters planning and every Soon task moves to Next, best effort per task, from one snapshot. A reason is required. Tasks that dependency order holds back stay put and are listed under `heldBack`, unless the call sends Move anyway. It is the only way an agent moves work into planning. |
| `dismissProviderWarning` | Dismiss provider warnings | Releases a warning-level provider limit hold so queued work resumes, with a required reason. A hold caused by a provider rejection is refused, even if its banner still shows an older warning; only you can resume past one. A failed release leaves the hold intact. |
| `runCodeExperiment` | Run code experiments | Starts scratch work in a registered repository or resumes `experimentId`. Retries keep one turn. Undispatched turns interrupt after five minutes; new work needs a new request ID. Grants are rechecked before dispatch. Scratch work expires and has no publishing or repository write access. |
| `reportFeedback` | Report factory problems | Records a problem the factory caused: a check the agent could not run, a worker that needed a restart, a wrong verdict. It takes a one-line summary and at least one piece of evidence (a run id, a command, error text or a file), and can link one task, run or approval in the workspace. The text is stored as quoted evidence, never becomes instructions, and never leaves the workspace. No default grant includes it. |
| `simulateCi` | Start CI simulations | Queues a PR Ready task into CI Simulation, like the merge card's button. It starts once pause, readiness and capacity holds clear. Other stages return `not-pr-ready`; an existing simulation or missing pull request returns a reason. Reusing `requestId` retains the original request or refusal. It never merges or approves a merge. No default grant. |
| `respondToApproval` | Per approval category | Answers an approval when the approval's rules and the session's category grant both allow it, with the fingerprint from `getApproval`. A dependency-order refusal comes back with its violations and fixes, and a fix or Move anyway can ride the response. [Approval categories](/docs/agent-access-approvals) covers it in full. |

Move retries retain one receipt; each tool keeps its restrictions. No tool grants secret writes, broad settings changes, worker/access management, destructive recovery, or movement through build, QA and pull request stages.

### Moving past a dependency-order warning

`createIdea`, `promoteIdea`, `scheduleFutureTask` and `pullNextSprint` accept `overridePipelineOrder: true` to land a move past a dependency-order warning. It needs the [Move anyway permission](/docs/agent-access-approvals) next to the tool's own, or the call is refused and nothing is written. The task's history names the session. Autopilot is always refused. Without the flag, an order refusal comes back with JSON (`pipeline_order_refused` and `pipelineOrder`): each violation with its severity, and the fixes.