DevBoy tools

    DevBoy Tools Reference

    Auto-generated by devboy tools docs from base_tool_definitions() and the static provider catalog. Do not edit by hand — re-run the command to refresh.

    DevBoy Tools v0.35.0 ships 55 provider-backed tools across 7 categories, 11 always-on context tools, and 10 providers.

    Provider Support Matrix

    ProviderIssue TrackerGit RepositoryEpicsMeeting NotesKnowledge BaseMessengerJira Structure
    GitHub✅✅—————
    GitLab✅✅—————
    ClickUp✅—✅————
    Jira✅—————⚠️
    Linear✅——————
    YouGile✅——————
    Confluence————✅——
    Fireflies———✅———
    Slack—————✅—
    Telegram—————✅—

    Legend: ✅ supported · ⚠️ conditional (see notes) · — not applicable.

    Conditional support

    • Jira → Jira Structure: requires the Structure plugin to be installed and accessible.

    Issue Tracker Tools

    Providers: GitHub, GitLab, ClickUp, Jira, Linear, YouGile.

    add_issue_comment

    Add a comment to an issue with optional file attachments (ClickUp only).

    ParameterTypeRequiredDescription
    bodystring✅Comment text
    keystring✅Issue key
    attachmentsarray<string>—File attachments (ClickUp only, max 10MB per file). Each: {fileData: base64, filename: string}

    assign_to_sprint

    Move one or more issues onto a Jira sprint. Pair with get_board_sprints to look up the numeric sprintId. Issues already on a sprint are silently moved.

    ParameterTypeRequiredDescription
    issueKeysarray<string>✅Issue keys to move onto the sprint. Must contain at least one key.
    sprintIdinteger✅Numeric sprint id. Use get_board_sprints to discover ids on a board. Min: 0

    create_issue

    Create a new issue in the configured provider.

    ParameterTypeRequiredDescription
    titlestring✅Issue title
    assigneesarray<string>—Assignee usernames
    descriptionstring—Issue description/body
    issueTypestring—Issue type (e.g., "Task", "Bug", "Story"). Default: "Task". Removed by providers that don't support it.
    labelsarray<string>—Labels to add
    markdownboolean—Whether the description is markdown (default: true). When true, ClickUp renders formatted text.
    parentIdstring—Parent issue key to create a subtask (e.g., 'CU-abc123' or 'DEV-42'). Only supported by ClickUp.
    projectIdstring—Jira project key (not numeric ID) for issue creation (e.g., "PROJ"). Optional — overrides the default project.

    delete_asset

    Delete a file attachment from an issue. Not all providers support this — check asset_capabilities first.

    ParameterTypeRequiredDescription
    asset_idstring✅Asset identifier to delete
    keystring✅Issue key (e.g. 'PROJ-123')

    download_asset

    Download a file attachment to local cache. Returns local file path when cache is available, base64-encoded content as fallback.

    ParameterTypeRequiredDescription
    asset_idstring✅Asset identifier from get_assets response
    context_typestring✅Context type: 'issue' or 'mr'. Allowed values: issue, mr
    keystring✅Issue key or MR key

    get_assets

    List file attachments for an issue or merge request.

    ParameterTypeRequiredDescription
    context_typestring✅Context type: 'issue' or 'mr' (merge request / pull request). Allowed values: issue, mr
    keystring✅Issue key (e.g. 'DEV-123', 'gitlab#42') or MR key (e.g. 'mr#42', 'pr#42')

    get_available_statuses

    Get available statuses for the issue tracker.

    No parameters.

    get_board_sprints

    List sprints visible on a Jira agile board. Use to discover the numeric sprintId accepted by create_issue / update_issue and assign_to_sprint. Returns name, state (active/future/closed), planned start/end, and goal — enough for the agent to pick the right sprint without a follow-up call.

    ParameterTypeRequiredDescription
    boardIdinteger✅Numeric Jira board id. The Agile / Boards REST endpoint returns sprints scoped to one board — there is no global sprint list. Min: 0
    statestring—Filter by sprint state. Default all returns every sprint on the board. Allowed values: active, future, closed, all

    get_custom_fields

    List custom fields available on the issue tracker, with their id, name, and field type. Use to discover the customfield_* id of a Jira instance — names like Epic Link, Sprint, Epic Name map to different ids on every deployment. Pair with customFields: { "<id>": <value> } on create_issue / update_issue for fields not yet exposed as first-class params.

    ParameterTypeRequiredDescription
    issueTypestring—Optional issue type. Reserved for providers that scope custom fields per create-screen context.
    limitinteger—Max fields to return after filtering (default 50). Sorted by name asc. Range: 1 – 200
    projectstring—Optional project key. Reserved for providers that scope custom fields per project; ignored on Jira's global /field endpoint.
    searchstring—Case-insensitive substring filter on the field name (e.g. "Epic" to find Epic Link and Epic Name).

    get_issue

    Get a single issue by key with optional comments and relations.

    ParameterTypeRequiredDescription
    keystring✅Issue key (e.g., 'gh#123', 'gitlab#456', 'CU-abc', 'DEV-42', 'jira#PROJ-123')
    includeCommentsboolean—Include issue comments (default: true)
    includeRelationsboolean—Include issue relations — parent, subtasks, dependencies (default: true)

    get_issue_comments

    Get comments for an issue.

    ParameterTypeRequiredDescription
    keystring✅Issue key

    get_issue_relations

    Get relations for an issue (parent, subtasks, linked issues).

    ParameterTypeRequiredDescription
    keystring✅Issue key

    get_issues

    Get issues from configured provider. Returns a list with filters.

    ParameterTypeRequiredDescription
    assigneestring—Filter by assignee username
    labelsarray<string>—Filter by label names
    limitinteger—Maximum number of results (default: 20). Range: 1 – 100
    nativeQuerystring—Native query passed directly to provider (e.g., Jira JQL). Replaces auto-generated filters. If the query omits a project clause, the default project is auto-injected.
    offsetinteger—Number of results to skip (default: 0). Min: 0
    projectKeystring—Project key to filter issues (e.g., "PROJ"). Overrides default project. Removed by providers that don't support it.
    searchstring—Search query for title and description
    sort_bystring—Sort by field (default: updated_at). Allowed values: created_at, updated_at
    sort_orderstring—Sort order (default: desc). Allowed values: asc, desc
    statestring—Filter by issue state (default: open). Allowed values: open, closed, all

    get_users

    Get users from the issue tracker (Jira). Search by name, project, or ID.

    ParameterTypeRequiredDescription
    maxResultsinteger—Max results (default: 50). Range: 1 – 1000
    projectKeystring—Get assignable users for project
    searchstring—Search by name or email
    userIdstring—Get specific user by ID

    Link two issues together (blocks, relates_to, etc.).

    ParameterTypeRequiredDescription
    linkTypestring✅Issue link type. Accepts canonical Jira names (Blocks, Relates, Causes, Implements, Created By, Duplicate, Cloners) and snake_case aliases (blocks, blocked_by, relates_to, causes, caused_by, implements, implemented_by, created_by, creates, duplicates, duplicated_by, clones, cloned_by). The *_by variants flip direction. Custom link types configured on the instance also work — pass the exact name. GitHub/GitLab providers ignore this field.
    sourceIssueKeystring✅Source issue key
    targetIssueKeystring✅Target issue key

    list_project_versions

    List Jira project versions / fixVersion targets (releases). Returns rich per-version payload (description, dates, released/archived flags, optional issue counts). Default filter hides archived versions and limits to 20 most recent (unreleased first, then released by releaseDate desc). For issue-level details on a release, follow up with get_issues and a JQL nativeQuery such as fixVersion = "<name>" — there is no per-id get tool by design.

    ParameterTypeRequiredDescription
    archivedstring—Filter by archived flag (default: "false" — hides archival noise). Allowed values: true, false, all
    includeIssueCountboolean—Fetch issue counts per version via Cloud ?expand=issuesstatus (default: false). Adds latency on large projects.
    limitinteger—Max versions to return (default: 20). Sorted by releaseDate desc; oldest archival entries trimmed first. Range: 1 – 200
    projectstring—Jira project key (e.g., "PROJ"). Defaults to the configured project.
    releasedstring—Filter by release state: "true" → only released, "false" → only unreleased, "all" → both (default: "all"). Allowed values: true, false, all

    Remove a link between two issues.

    ParameterTypeRequiredDescription
    linkTypestring✅Issue link type to remove. Accepts the same canonical names and snake_case aliases as link_issues (Blocks, Causes, Implements, Created By, Duplicate, Cloners, plus *_by direction flips and subtask). Custom link types pass through as-is.
    sourceIssueKeystring✅Source issue key
    targetIssueKeystring✅Target issue key

    update_issue

    Update an existing issue. Only provided fields will be changed.

    ParameterTypeRequiredDescription
    keystring✅Issue key
    assigneesarray<string>—New assignees
    descriptionstring—New description
    labelsarray<string>—New labels (replaces existing)
    markdownboolean—Whether the description is markdown (default: true). When true, ClickUp renders formatted text.
    parentIdstring—Parent issue key to move task as subtask (e.g., 'CU-abc123' or 'DEV-42'). Only supported by ClickUp.
    statestring—New state (generic open/closed). For ClickUp custom statuses ("in progress", "review", "to do", …) use status instead — get_available_statuses lists valid names. Allowed values: open, closed
    statusstring—Provider-specific status name. ClickUp: any custom status from get_available_statuses (e.g. "in progress", "review"). Other providers: ignored. Takes precedence over state when both are set.
    titlestring—New title

    upload_asset

    Upload a file attachment to an issue. Returns the download URL.

    ParameterTypeRequiredDescription
    context_typestring✅Context type (currently only 'issue' is supported for uploads). Allowed values: issue
    fileDatastring✅Base64-encoded file content
    filenamestring✅Original filename (e.g. 'screenshot.png')
    keystring✅Issue key (e.g. 'DEV-123')

    upsert_project_version

    Create or partially update a Jira project version, keyed by (project, name). If a version with this name exists, fields you supply are updated and unspecified fields are preserved. If not, a new version is created. Useful for writing release notes (description) or closing a release (released: true, releaseDate).

    ParameterTypeRequiredDescription
    namestring✅Version name — both the lookup key and, on create, the value (e.g., "3.18.0").
    archivedboolean—Archive (true) / unarchive (false) the version.
    descriptionstring—Release notes / version description. Markdown-style text is preserved on Server/DC; Cloud accepts plain text.
    projectstring—Jira project key (e.g., "PROJ"). Defaults to the configured project.
    releaseDatestring—Planned or actual release date (YYYY-MM-DD).
    releasedboolean—Mark released (true) / unreleased (false). Pair with releaseDate when closing a release.
    startDatestring—Planned start date as ISO 8601 calendar date (YYYY-MM-DD).

    Git Repository Tools

    Providers: GitHub, GitLab.

    create_merge_request

    Create a new merge request (GitLab) or pull request (GitHub).

    ParameterTypeRequiredDescription
    source_branchstring✅Source branch
    target_branchstring✅Target branch
    titlestring✅MR/PR title
    descriptionstring—MR/PR description
    draftboolean—Create as draft (default: false)
    labelsarray<string>—Labels
    reviewersarray<string>—Reviewers

    create_merge_request_comment

    Add a comment to a merge request. Can be general or inline code review.

    ParameterTypeRequiredDescription
    bodystring✅Comment text
    keystring✅MR/PR key
    commit_shastring—Commit SHA for inline comment
    discussion_idstring—Reply to existing discussion
    file_pathstring—File path for inline comment
    lineinteger—Line number for inline comment
    line_typestring—Line type (default: new). Allowed values: old, new

    get_job_logs

    Get CI/CD job logs. Modes: smart (auto errors), search (pattern), paginated, full.

    ParameterTypeRequiredDescription
    jobIdstring✅Job ID from get_pipeline
    contextinteger—Context lines around match (default: 5)
    fullboolean—Return entire log
    limitinteger—Lines to return (default: 200, max: 1000). Range: 1 – 1000
    maxMatchesinteger—Max search results (default: 20)
    offsetinteger—Start line for paginated mode
    patternstring—Regex/keyword search pattern

    get_merge_request

    Get a single merge request by key (e.g., 'pr#123', 'mr#456').

    ParameterTypeRequiredDescription
    keystring✅MR/PR key

    get_merge_request_diffs

    Get file diffs for a merge request.

    ParameterTypeRequiredDescription
    keystring✅MR/PR key

    get_merge_request_discussions

    Get discussions/review comments for a merge request with code positions.

    ParameterTypeRequiredDescription
    keystring✅MR/PR key
    limitinteger—Max discussions to return (default: all). Min: 1
    offsetinteger—Skip N discussions (default: 0). Min: 0

    get_merge_requests

    Get merge requests / pull requests from configured provider.

    ParameterTypeRequiredDescription
    authorstring—Filter by author username
    labelsarray<string>—Filter by label names
    limitinteger—Maximum results (default: 20). Range: 1 – 100
    source_branchstring—Filter by source branch
    statestring—Filter by state (default: open). Allowed values: open, closed, merged, all
    target_branchstring—Filter by target branch

    get_pipeline

    Get CI/CD pipeline status for branch or MR/PR with job details.

    ParameterTypeRequiredDescription
    branchstring—Branch name (default: main)
    includeFailedLogsboolean—Include error extraction for failed jobs (default: true)
    mrKeystring—MR/PR key (priority over branch)

    run_pipeline_job

    Run an existing manual GitLab CI job after verifying that it belongs to the supplied pipeline and is still manual.

    ParameterTypeRequiredDescription
    jobIdstring✅Manual job ID returned by get_pipeline
    pipelineIdstring✅Pipeline ID returned by get_pipeline
    jobInputsobject—Optional typed GitLab job inputs as an object of JSON values
    variablesobject—Optional CI variables as an object whose values are strings

    update_merge_request

    Update a merge request / pull request (title, description, state, labels, draft).

    ParameterTypeRequiredDescription
    keystring✅MR key (e.g. 'mr#1', 'pr#42')
    descriptionstring—New description / body (supports markdown)
    labelsarray<string>—New labels (replaces existing)
    statestring—Change MR state. Allowed values: close, reopen
    titlestring—New title

    Epics Tools

    Providers: ClickUp.

    create_epic

    Create a new epic.

    ParameterTypeRequiredDescription
    titlestring✅Epic title
    descriptionstring—Epic description

    get_epics

    Get epics (high-level tasks) from the issue tracker.

    ParameterTypeRequiredDescription
    limitinteger—Max results (default: 50). Range: 1 – 100
    offsetinteger—Skip N results (default: 0). Min: 0
    searchstring—Search in epic title

    update_epic

    Update an existing epic.

    ParameterTypeRequiredDescription
    epicKeystring✅Epic key (e.g., 'CU-abc', 'DEV-123')
    assigneesarray<string>—Assignees to set
    descriptionstring—New description
    goalIdstring—Goal ID (G1-G9) to associate with the epic
    labelsarray<string>—Labels to set
    prioritystring—New priority (urgent/high/normal/low)
    statestring—New epic state (generic open/closed). For ClickUp custom statuses use status.
    statusstring—Provider-specific status name. Same as update_issue.status — for ClickUp, any custom status from get_available_statuses. Takes precedence over state.
    titlestring—New title

    Meeting Notes Tools

    Providers: Fireflies.

    get_meeting_notes

    Get meeting notes and transcripts with optional filters (date range, participants, host).

    ParameterTypeRequiredDescription
    from_datestring—Filter from date (ISO 8601, e.g., '2025-01-01T00:00:00Z')
    host_emailstring—Filter by host email
    limitinteger—Maximum number of results (default: 50). Range: 1 – 50
    offsetinteger—Number of results to skip (default: 0). Min: 0
    participantsarray<string>—Filter by participant email addresses
    to_datestring—Filter to date (ISO 8601)

    get_meeting_transcript

    Get the full transcript for a meeting. Returns speaker-attributed sentences with timestamps.

    ParameterTypeRequiredDescription
    meeting_idstring✅Meeting ID from get_meeting_notes
    formatstring—Output format: 'flat' (default, per-sentence) or 'grouped' (same-speaker runs collapsed). Allowed values: flat, grouped
    limitinteger—Maximum number of sentences (default: 50, max: 500). Range: 1 – 500
    offsetinteger—Number of sentences to skip for pagination (default: 0). Min: 0
    search_textstring—Search sentence text (case-insensitive substring match)
    speaker_filterstring—Filter sentences by speaker name (case-insensitive substring match)

    search_meeting_notes

    Search across meetings by keywords, topics, or action items, with optional filters (date range, participants, host).

    ParameterTypeRequiredDescription
    querystring✅Search query
    from_datestring—Filter from date (ISO 8601)
    host_emailstring—Filter by host email
    limitinteger—Maximum number of results (default: 50). Range: 1 – 50
    offsetinteger—Number of results to skip (default: 0). Min: 0
    participantsarray<string>—Filter by participant email addresses
    to_datestring—Filter to date (ISO 8601)

    Knowledge Base Tools

    Providers: Confluence.

    create_knowledge_base_page

    Create a knowledge base page in a space.

    ParameterTypeRequiredDescription
    contentstring✅Page body content
    spaceKeystring✅Target space key
    titlestring✅Page title
    contentTypestring—Content representation supplied by the caller. Allowed values: markdown, html, storage
    labelsarray<string>—Labels to set on the page
    parentIdstring—Optional parent page ID

    get_knowledge_base_page

    Get a knowledge base page with content, labels, and ancestors.

    ParameterTypeRequiredDescription
    pageIdstring✅Knowledge base page ID

    get_knowledge_base_spaces

    List available knowledge base spaces.

    No parameters.

    list_knowledge_base_pages

    List pages in a knowledge base space with pagination.

    ParameterTypeRequiredDescription
    spaceKeystring✅Space key to list pages from
    cursorstring—Provider pagination cursor/token
    limitinteger—Maximum number of results (default: 25). Range: 1 – 100
    offsetinteger—Number of results to skip when offset pagination is supported. Min: 0
    parentIdstring—Optional ancestor/parent page ID to scope the listing
    searchstring—Optional free-text title/content filter

    search_knowledge_base

    Search knowledge base pages across spaces using free text or provider-native syntax such as CQL.

    ParameterTypeRequiredDescription
    querystring✅Free-text query or provider-native search expression
    cursorstring—Provider pagination cursor/token
    limitinteger—Maximum number of matches to return. Range: 1 – 100
    rawQueryboolean—Whether query should be treated as raw provider-native syntax
    spaceKeystring—Restrict search to a specific space key

    update_knowledge_base_page

    Update a knowledge base page title, content, metadata, or labels.

    ParameterTypeRequiredDescription
    pageIdstring✅Knowledge base page ID
    contentstring—New page body content
    contentTypestring—Content representation supplied by the caller. Allowed values: markdown, html, storage
    labelsarray<string>—Labels to replace on the page
    parentIdstring—Optional new parent page ID
    titlestring—New page title
    versioninteger—Expected current version for optimistic locking. Min: 1

    Messenger Tools

    Providers: Slack, Telegram.

    get_chat_messages

    Get message history for a chat or fetch replies for a specific thread.

    ParameterTypeRequiredDescription
    chat_idstring✅Messenger chat ID
    cursorstring—Provider pagination cursor
    limitinteger—Maximum number of messages to return. Range: 1 – 1000
    sincestring—Only include messages after this provider timestamp
    thread_idstring—Thread identifier to fetch replies for
    untilstring—Only include messages before this provider timestamp

    get_messenger_chats

    List available messenger chats, channels, groups, or direct messages.

    ParameterTypeRequiredDescription
    chat_typestring—Optional chat type filter. Allowed values: direct, group, channel
    cursorstring—Provider pagination cursor
    include_inactiveboolean—Include archived or inactive chats
    limitinteger—Maximum number of chats to return. Range: 1 – 1000
    searchstring—Optional chat name search

    search_chat_messages

    Search messages across accessible chats or within a specific chat.

    ParameterTypeRequiredDescription
    querystring✅Message search query
    chat_idstring—Optional chat ID to scope the search
    cursorstring—Provider pagination cursor
    limitinteger—Maximum number of matches to return. Range: 1 – 1000
    sincestring—Only include messages after this provider timestamp
    untilstring—Only include messages before this provider timestamp

    send_message

    Send a message to a chat or as a threaded reply.

    ParameterTypeRequiredDescription
    chat_idstring✅Messenger chat ID
    textstring✅Message body
    reply_to_idstring—Direct parent message ID when supported
    thread_idstring—Thread identifier to post as a threaded reply

    Jira Structure Tools

    Providers: Jira (conditional).

    add_structure_rows

    Add items (Jira issues or folders) to a Structure. Specify position with under (parent row) and/or after (sibling row). Use forestVersion for optimistic concurrency.

    ParameterTypeRequiredDescription
    itemsarray<string>✅Items to add
    structureIdinteger✅Structure ID
    afterinteger—Sibling row ID — items placed after this row
    forestVersioninteger—Forest version for optimistic locking (from get_structure_forest)
    underinteger—Parent row ID — items become children of this row

    create_structure

    Create a new Jira Structure. After creation, use add_structure_rows to populate and save_structure_view to configure columns.

    ParameterTypeRequiredDescription
    namestring✅Structure name
    descriptionstring—Structure description

    get_structure_forest

    Get the hierarchy tree of a Jira Structure. Returns nested tree with rowId, itemId (Jira issue key), itemType, and children. Supports pagination for large structures.

    ParameterTypeRequiredDescription
    structureIdinteger✅Structure ID. Use get_structures to find it.
    limitinteger—Max rows to return (default: 200). Range: 1 – 10000
    offsetinteger—Offset for pagination (default: 0). Min: 0

    get_structure_values

    Read column values (including Expr formulas like SUM, PROGRESS, COUNT) for specific rows in a Jira Structure. Values are computed server-side.

    ParameterTypeRequiredDescription
    columnsarray<string>✅Columns to read
    rowsarray<integer>✅Row IDs to read values for
    structureIdinteger✅Structure ID

    get_structure_views

    Get views for a Jira Structure. Without viewId: lists all views. With viewId: returns full view configuration (columns, grouping, sorting, filter).

    ParameterTypeRequiredDescription
    structureIdinteger✅Structure ID
    viewIdinteger—View ID for full config (optional — omit to list all views)

    get_structures

    List all available Jira Structures. Returns structure ID, name, and description. Requires Jira with Structure plugin.

    No parameters.

    move_structure_rows

    Move rows within a Jira Structure hierarchy. Specify new position with under (new parent) and/or after (sibling).

    ParameterTypeRequiredDescription
    rowIdsarray<integer>✅Row IDs to move (from get_structure_forest)
    structureIdinteger✅Structure ID
    afterinteger—Sibling row ID to place after
    forestVersioninteger—Forest version for optimistic locking
    underinteger—New parent row ID

    remove_structure_row

    Remove a row from a Jira Structure. Only removes from the structure hierarchy — the underlying Jira issue is NOT deleted.

    ParameterTypeRequiredDescription
    rowIdinteger✅Row ID to remove (from get_structure_forest)
    structureIdinteger✅Structure ID

    save_structure_view

    Create or update a Jira Structure view. Views define column layout (fields and formulas), grouping, sorting, and filters. Omit id to create new.

    ParameterTypeRequiredDescription
    namestring✅View name
    structureIdinteger✅Structure ID this view belongs to
    columnsarray<string>—Column definitions
    filterstring—JQL filter expression
    groupBystring—Field name to group by
    idinteger—View ID to update (omit to create new)
    sortBystring—Field name to sort by

    Context Management Tools

    Always-on tools attached to every tools/list response, independent of which providers are configured. They let the agent inspect or switch the active context.

    list_contexts

    List configured contexts and indicate the active context.

    No parameters.

    use_context

    Switch active context at runtime.

    ParameterTypeRequiredDescription
    namestring✅Context name to activate

    get_current_context

    Get current active context name.

    No parameters.

    secrets_list

    List secrets the active context's manifest declares. Returns metadata only — values are never included. Optional filter narrows by path substring, scope, status, or whether to include framework-internal paths.

    ParameterTypeRequiredDescription
    include_internalboolean—Include framework-internal paths (default: false).
    path_containsstring—Substring to match against the full ADR-020 path.
    scopestring—Exact match against the first path segment (e.g. team / personal).
    statusstring—Lifecycle status filter computed from expires_at.. Allowed values: registered, expiring, expired

    secrets_describe

    Describe one secret by ADR-020 path. Returns the same metadata fields as secrets_list plus description, retrieval URL, rotation method, last rotated date, rotation cadence, and pattern ID. The value is never returned.

    ParameterTypeRequiredDescription
    pathstring✅Full ADR-020 path to describe.

    secrets_request_provision

    Open the provisioning UI dialog for the given ADR-020 path. The dialog hands the user-entered value directly to the local daemon — the agent never sees it. Returns a request_id that can be polled with secrets_poll_status. Mode defaults to provision; pass rotation to surface the destructive-confirm checkbox. Pending requests expire 5 minutes after issuance.

    ParameterTypeRequiredDescription
    pathstring✅Full ADR-020 path to provision.
    modestring—Dialog mode (default: provision).. Allowed values: provision, rotation

    secrets_poll_status

    Poll a provisioning or rotation request issued by secrets_request_provision / secrets_request_rotation. Returns one of pending / ok / cancelled / expired / failed plus the request's age in seconds and the path it was opened for.

    ParameterTypeRequiredDescription
    request_idstring✅Opaque id returned by request_provision / request_rotation.

    secrets_request_rotation

    Open the rotation UI dialog for the given ADR-020 path. Same lifecycle as secrets_request_provision but the dialog surfaces the destructive-confirm checkbox so the user explicitly acknowledges that the existing value is being overwritten. Reuses secrets_poll_status for status. Pending requests expire 5 minutes after issuance.

    ParameterTypeRequiredDescription
    pathstring✅Full ADR-020 path to rotate.

    secrets_request_use_approval

    Open the use-approval dialog for an ADR-020 path whose approve_on_use is set to session or per-call. The agent supplies a short human-facing reason that the dialog renders verbatim alongside the path; the user picks once, session, or denied. Returns a request_id to poll via secrets_poll_status. Pending requests expire 5 minutes after issuance; ttl_seconds may shorten the window but never extend it. The agent never sees the secret — only whether the user approved its use.

    ParameterTypeRequiredDescription
    pathstring✅Full ADR-020 path the agent intends to resolve.
    reasonstring✅Short human-facing reason rendered in the dialog (e.g. 'pushing image to staging registry').
    ttl_secondsinteger—Optional lifetime in seconds; capped at the registry-wide TTL (5 minutes).

    secrets_propose_metadata

    Suggest metadata edits for an existing ADR-020 path. The dialog renders the manifest's current values as the diff baseline (read straight from the index — agent strings never replace trusted fields, mitigating prompt-injection). The user picks which proposed fields to accept. Reuses secrets_poll_status for status. Pending requests expire 5 minutes after issuance.

    ParameterTypeRequiredDescription
    fieldsobject✅Proposed field overrides (description, retrieval_url, rotate_every_days, expires_at, pattern_id). Omitted fields are not proposed for change.
    pathstring✅Full ADR-020 path to edit.

    secrets_propose_new_path

    Suggest registering a new secret at the given path. The dialog opens with the suggested path editable and the proposed metadata visible in a diff column for review. The user has the final say on the path and the metadata that lands in the manifest. Reuses secrets_poll_status for status. Pending requests expire 5 minutes after issuance.

    ParameterTypeRequiredDescription
    metadataobject✅Proposed metadata fields for the new entry.
    suggested_pathstring✅Suggested ADR-020 path; user may edit.