Skip to content

process: start agent CLIs in a new session so Ctrl-C ends them at once - #7832

Queued
anton-107 wants to merge 5 commits into
mainfrom
agent-cli-new-session-interrupt
Queued

anton-107 wants to merge 5 commits into
mainfrom
agent-cli-new-session-interrupt

Conversation

@anton-107

Copy link
Copy Markdown
Contributor

Changes

process.BackgroundInGroup now starts the child as the leader of a new session (Setsid) instead of only putting it in a new process group (Setpgid). The aitools installer and agent detection use this helper when they run agent CLIs such as claude plugin ....

 BackgroundInGroup(ctx, args)
-  Background(ctx, args, WithProcessGroup())
+  Background(ctx, args, WithProcessGroup(), withNewSession())
  • withNewSession (in libs/process/interrupt_unix.go) must come after WithProcessGroup. It clears Setpgid and sets Setsid, because setpgid fails for a process that is already a session leader. A session leader's group ID equals its PID, so the existing group signals (kill(-pid, ...)) still reach the child and all of its descendants.
  • reapProcessGroup (in libs/process/group_unix.go) now also runs for a Setsid child. Without this, the final group SIGKILL after the grace period would be skipped, and a descendant that ignores SIGTERM would be left running.

Why

BackgroundInGroup moves the child out of the terminal's foreground group. When the user presses Ctrl-C, the CLI stops the group with SIGTERM and then ends itself the way the interrupt would have.

Some agent CLIs (Claude Code is one) read the terminal when they get SIGTERM. A process in a background group of the terminal's session that reads the terminal gets SIGTTIN and stops. The child then sat stopped until the SIGKILL at the end of the 10s grace period, so Ctrl-C during an AI tools install took about 10 seconds to take effect. A child in its own session has no controlling terminal: its open("/dev/tty") fails at once, it exits, and Ctrl-C ends the CLI right away.

Tests

  • New TestBackgroundInGroupInterruptChildReadsTerminal (Linux only, since it opens a pseudo-terminal with platform-specific ioctls). The test starts itself as a helper process in the foreground group of a fresh pty. The helper runs BackgroundInGroup on a shell that, on SIGTERM, reads /dev/tty before it exits. The test then sends SIGINT to the helper and checks that the helper is ended by SIGINT within half the grace period. Before this change the child was stopped by SIGTTIN and the helper outlived that deadline.
  • New TestBackgroundInGroupReapsGrandchildAfterEscalation: the child ignores SIGTERM and has a grandchild. After the context is cancelled, the test checks that the escalation SIGKILL reaches the grandchild. This covers the reapProcessGroup change for session leaders.
  • The existing libs/process tests pass, including TestBackgroundInGroupForwardsInterrupt.

## Changes

`process.BackgroundInGroup` now starts the child as the leader of a new session (`Setsid`) instead of only putting it in a new process group (`Setpgid`). The aitools installer and agent detection use this helper when they run agent CLIs such as `claude plugin ...`.

```diff
 BackgroundInGroup(ctx, args)
-  Background(ctx, args, WithProcessGroup())
+  Background(ctx, args, WithProcessGroup(), withNewSession())
```

- `withNewSession` (in `libs/process/interrupt_unix.go`) must come after `WithProcessGroup`. It clears `Setpgid` and sets `Setsid`, because `setpgid` fails for a process that is already a session leader. A session leader's group ID equals its PID, so the existing group signals (`kill(-pid, ...)`) still reach the child and all of its descendants.
- `reapProcessGroup` (in `libs/process/group_unix.go`) now also runs for a `Setsid` child. Without this, the final group `SIGKILL` after the grace period would be skipped, and a descendant that ignores `SIGTERM` would be left running.

## Why

`BackgroundInGroup` moves the child out of the terminal's foreground group. When the user presses Ctrl-C, the CLI stops the group with `SIGTERM` and then ends itself the way the interrupt would have.

Some agent CLIs (Claude Code is one) read the terminal when they get `SIGTERM`. A process in a background group of the terminal's session that reads the terminal gets `SIGTTIN` and stops. The child then sat stopped until the `SIGKILL` at the end of the 10s grace period, so Ctrl-C during an AI tools install took about 10 seconds to take effect. A child in its own session has no controlling terminal: its `open("/dev/tty")` fails at once, it exits, and Ctrl-C ends the CLI right away.

## Tests

- New `TestBackgroundInGroupInterruptChildReadsTerminal` (Linux only, since it opens a pseudo-terminal with platform-specific ioctls). The test starts itself as a helper process in the foreground group of a fresh pty. The helper runs `BackgroundInGroup` on a shell that, on `SIGTERM`, reads `/dev/tty` before it exits. The test then sends `SIGINT` to the helper and checks that the helper is ended by `SIGINT` within half the grace period. Before this change the child was stopped by `SIGTTIN` and the helper outlived that deadline.
- New `TestBackgroundInGroupReapsGrandchildAfterEscalation`: the child ignores `SIGTERM` and has a grandchild. After the context is cancelled, the test checks that the escalation `SIGKILL` reaches the grandchild. This covers the `reapProcessGroup` change for session leaders.
- The existing `libs/process` tests pass, including `TestBackgroundInGroupForwardsInterrupt`.

Co-authored-by: Isaac <no-reply@databricks.com>

@review-oss-bot review-oss-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review at 5d211f7. Each finding was verified against the code.

No blocking issues found. 1 non-blocking comment(s) below.

The PR moves agent CLI children into their own session (Setsid) so that Ctrl-C during an install is responsive instead of waiting ~10 s for the SIGKILL escalation. The approach is sound and covered by two new tests. Two existing comments that describe the Setpgid mechanism need updating now that the live code path uses Setsid instead.

Comment thread libs/process/group_unix.go Resolved
@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 25f98fd

Run: 44763267483

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 272 19 6:58
💚​ aws-windows-latest-4core-16gb 1 274 17 5:21
💚​ azure linux-2core-8gb 1 271 19 5:56
💚​ azure-windows-latest-4core-16gb 1 273 17 4:51
💚​ gcp linux-2core-8gb 1 272 19 6:18
💚​ gcp-windows-latest-4core-16gb 1 274 17 4:14
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 3 slowest tests (at least 2 minutes):
duration env testname
4:06 azure-windows-latest-4core-16gb TestAccept
4:04 gcp-windows-latest-4core-16gb TestAccept
4:00 aws-windows-latest-4core-16gb TestAccept

Co-authored-by: Isaac <no-reply@databricks.com>

@simonfaltum simonfaltum left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review from simonfaltum's review agent (pr-review skill) at 3eeb7ed. Each finding was verified against the code; simonfaltum may follow up.

Not approving yet: part of the automated review did not complete.

This PR starts the agent CLIs run by BackgroundInGroup in a new session (Setsid). A CLI that reads /dev/tty after SIGTERM then fails at once instead of being stopped by SIGTTIN, so Ctrl-C no longer waits out the 10s grace period. The final group SIGKILL now also covers session leaders. The mechanism is correct: group signals still reach all descendants, and clearing Setpgid avoids the EPERM a session leader would get. Both new tests pass at head and fail against the base code. Only nits remain (a changelog fragment, a duplicated test, comment wrapping), plus one non-blocking question about agent CLIs that may need a terminal.

Questions

  1. With Setsid, the agent CLIs that BackgroundInGroup runs have no controlling terminal. That covers the plugin --help probe, plugin marketplace list/add/remove, and install/update/uninstall, for every plugin agent, including the auto-install after a command. Without one, an open of /dev/tty fails with ENXIO. Before this change such a CLI could open the terminal and write to it; only a read stopped it. Did you check that the plugin subcommands of the agents other than Claude Code (Codex, Copilot, Cursor, Gemini, OpenCode, …) still work without a terminal? If one needs it, you could give the new session only to the commands that need it and keep the rest in a process group. (non-blocking)

Accepted answers

Comment thread libs/process/interrupt_unix.go Resolved
Comment thread libs/process/interrupt_unix_test.go Resolved
Comment thread libs/process/group_unix.go Resolved
Add a changelog entry for the Ctrl-C fix, run the SIGKILL escalation test
over both runners in one table-driven test, and reword the group signal
comment.

Co-authored-by: Isaac <no-reply@databricks.com>

@simonfaltum simonfaltum left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review from simonfaltum's review agent (pr-review skill) at eb9f01b. Each finding was verified against the code; simonfaltum may follow up.

No blocking issues found, approving. 3 non-blocking comment(s) and 1 question(s) below.

This PR starts the agent CLIs that BackgroundInGroup runs in their own session, so a CLI that reads /dev/tty after SIGTERM fails at once instead of being stopped by SIGTTIN, and Ctrl-C no longer waits out the 10s grace period; the final group SIGKILL now also covers session leaders. The mechanism is correct: the new pty test fails against the base code and passes at head, and the session escalation subtest catches a revert of the reapProcessGroup change. What's left is three nits (a stale test name in the description, a changelog line that names only install, and test cleanup on failure), a short non-blocking question about withNewSession's ordering, and the earlier question about agent CLIs that may need a terminal, which is still open.

Questions

  1. withNewSession only works when it runs after WithProcessGroup: it clears the Setpgid that option set and dereferences c.SysProcAttr without a nil check. That holds at its single call site today, so it is not a bug. Would you rather make it self-contained (for example a session variant of WithProcessGroup that sets Setsid and never sets Setpgid), or keep the documented ordering as it is? (non-blocking)

Accepted answers

  • Why the pty regression test is Linux-only (no macOS coverage)

Comment thread libs/process/interrupt_linux_test.go Resolved
Comment thread .nextchanges/cli/7832.md Resolved
Comment thread libs/process/group_unix_test.go Resolved
anton-107 and others added 2 commits November 20, 2026 15:17
Co-authored-by: Isaac <no-reply@databricks.com>
…g entry

Kill the helper and its child's group when the terminal test fails, log the
helper's terminal output, and check that the grandchild was stopped. Kill the
escalation test's grandchild on failure and fix the comment about the ignored
SIGTERM it inherits. Name update and uninstall in the changelog entry too.

Co-authored-by: Isaac <no-reply@databricks.com>
@anton-107
anton-107 added this pull request to the merge queue Nov 20, 2026
Any commits made after this event will not be merged.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants