Human-approved actions: jobs propose, people approve, the broker writes

Open
#46 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
django, python

Research direction

Start by locating how jobs currently declare and receive read-only tool capabilities, then trace the dashboard and Slack approval flows and workspace role checks. The issue does not name files or tests, so first map those entry points before estimating implementation. Done means both proposed actions remain unwritten until approval, rejected actions never run, approved actions run once with the recorded arguments, and unauthorized members cannot approve.

Written by the indexing model from the issue text.

Description

area: access idea

Goal

Let a job draft changes to other systems, and let a person approve each one before it happens. The agent does the work of writing the ticket or comment. A person keeps the final say on anything that changes another system.

Why

Today a job has two options, and both fall short.

Read-only tools. The job posts a report and someone copies its findings into Linear or a PR by hand. The findings stop at the report.

Write tools granted directly. An owner adds a write tool such as linear create_issue under requires. The agent then calls it during the run with no one checking. A wrong model answer, or a prompt injection in a PR description, can file duplicate tickets, post a wrong comment, or put sensitive text somewhere public. All of that happens before anyone looks.

#218 solved this for one case. The agent proposes GitHub issues, and SecondShift opens them after the run with a token the sandbox never sees. But every proposal opens automatically. No one approves them one by one.

Example

A weekly review job finds a flaky test and a stalled PR. It has two write tools. Calling one does not write anything. It records a proposal:

Proposal 1  linear.create_issue
  team:  ENG
  title: "Flaky test: test_retry_backoff"
  body:  "Failed 4 of 20 CI runs this week. Last failure: ..."
  why:   "Recurring CI failure, no existing ticket"

Proposal 2  github.create_comment
  pr:    #812
  body:  "This has waited 6 days for review. Can someone take a look?"
  why:   "Stalled review"

The run's message links to the proposals. A reviewer opens them in the dashboard:

  • They approve proposal 1. SecondShift creates the Linear ticket exactly as shown, once, with the workspace's Linear connection. The run page shows the ticket link.
  • They reject proposal 2 because the reviewer it asks for is on vacation. Nothing is posted.
  • Someone without the right role can see both proposals but cannot decide them.
  • The run page records who decided each proposal and what came back.

Scope

  • An owner grants a write tool as needs approval for each call. The agent sees the tool as usual. When it calls the tool, the broker stores the tool, the exact arguments and the reason, and tells the agent the call is waiting for approval.
  • People approve or reject each proposal. Approving runs the call exactly as proposed, once. Changing the arguments means a new proposal.
  • The call runs on the server with the workspace's connection. The credential never reaches the sandbox or the model.
  • Every proposal, decision and result is recorded with who decided it.

Who approves and where

The right approver is usually not an owner or admin. It is whoever owns the outcome: the team lead whose Linear board gets the ticket, or the engineer on the PR. These people do not open SecondShift. They see a message in their team channel.

So the assumption is: an approver reacts to a message, decides in under a minute, and never browses SecondShift. If approving means logging into an admin console and finding the run, proposals will sit until they expire.

How it works:

  1. A run finishes. The job's channel gets one message: "Weekly review proposes 2 actions". Each proposal shows the tool and a short summary, with Approve, Reject and View.
  2. Someone clicks Approve. SecondShift checks that they are a workspace member allowed to approve for this job, runs the call, and edits the message to say "Approved by Alex, created ENG-142".
  3. View, or a link from email or a webhook, opens a page for that one proposal: the full arguments and the two buttons, without the admin sidebar.
  4. Admins see all open proposals on the run page and in a queue. That is for oversight. Most decisions happen in chat.

Each proposal has one decision. Whoever acts first decides it, and every other place shows the result.

Use the target's own review step when it has one. If a Linear team uses Triage, creating the ticket there is already "propose, then a person approves", with no SecondShift UI. This fits tickets and issues, not comments or edits.

What it takes

  1. A reviewer who is not an operator. Members can only view today. Add an action such as "approve proposed actions", held by admins and owners and by members named as reviewers on a job. This is the first role that acts without running SecondShift.
  2. A page for one proposal. Works on a phone, shows the tool, the connection, the full arguments and the reason, with approve and reject. Every link points here.
  3. Proposals on the run page and an admin queue. For oversight and for anything that was not decided in chat.
  4. Links in run messages. The message says how many proposals are waiting and links to each one. Run notifications are outgoing webhooks today, so the first version uses links, not buttons.
  5. A way to know which tools write. Nothing records this yet. The owner chooses "needs approval for each call" when granting the tool, and the access review shows it as "changes data". MCP tool hints like readOnlyHint can set the default but cannot be trusted alone.
  6. Running approved calls. Reuse run deliveries (#201) for status and retries. Lock the proposal when it starts running so two clicks cannot run it twice. If a call times out and the result is unknown, mark it as unknown and do not retry automatically.
  7. Expiry. A proposal from last week may no longer make sense, for example when the PR is already merged. Proposals expire after a set time, and expired ones cannot be approved.

Order

  1. Proposals, the single-proposal page, links in run messages, and reviewers on a job.
  2. Approve in Slack. Buttons need a Slack app with an interactivity endpoint, signed request checks, and a one-time sign-in that links a Slack user to a workspace member, so not everyone in the channel can approve. Webhooks cannot do this. It uses the same backend as step 1.
  3. Fold #218 into this. open_issues becomes a proposal with an "approve automatically" setting for teams that want today's behavior.

Not the main path

A full approvals inbox in the current dashboard. It puts the decision where approvers are least likely to be, and it would mean building a second app for people who are not admins.

Validation

Have a job propose a Linear issue and a PR comment. Confirm that:

  • nothing is written before approval
  • a rejected proposal never runs
  • an approved proposal runs exactly once, even if approve is clicked twice
  • a member without permission cannot approve
  • an expired proposal cannot be approved
  • the run page shows who decided each proposal and the result
Dominant language
Python
Stars
1
Forks
1
Avg merge
1h 9m
Merged PRs (30d)
322

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from piotrekno1/second-shift

All issues in piotrekno1/second-shift

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.