jackherd 1.16.0 → 1.18.0

package/kit/hooks/hooks/merge-guard/decision.ts

@@ -2,6 +2,7 @@ import { FULL_COMMIT } from '../shared/commit'
 import { inlineScript, isOption, isProgramPosition, programName } from '../shared/program-position'
 import {
   expandingHereDocumentAdvice,
+  expandsBraces,
   isExpanded,
   parseShell,
   ShellParseError,
@@ -17,6 +18,15 @@ import {
   shellDefinitionHint,
 } from '../shared/shell-aliases'
 import { GLOB, resolvePlainXargs, XARGS } from '../shared/xargs-program'
+import {
+  AGENT_INPUT_COMMANDS,
+  AGENT_TARGET,
+  HERD_WORDS,
+  LIFTABLE_PANE_INPUT,
+  OTHER_SERVER_OPTIONS,
+  PANE_ID,
+  PANE_INPUT_COMMANDS,
+} from './pane-input'
 
 export type MergeGuardDecision = { kind: 'pass' } | { kind: 'ask'; reason: string }
 
@@ -33,27 +43,75 @@ export type GuardPolicy = {
   /** The guarded commands as words: a program and the plain words after it, such as `gh pr merge`. */
   commands: readonly string[]
   /**
-   * Whether the merge of this pull request may pass without a question: the user approved its branch, a standing
-   * approval covers the plan of its lane, or every file of it matches `merge.withoutChecks`. Asked only for a plain `gh pr merge <number>`.
+   * Whether the merge of this pull request may pass without a question: the user approved its branch with the change
+   * id (patch id of its diff) the pull request still carries, a standing approval covers the plan of its lane, or
+   * every file of it matches `merge.withoutChecks`. Asked only for a plain `gh pr merge <number>`.
    * A throw counts as not approved; a note is not approved either, and the question carries it.
    */
   isMergeApproved: (merge: PlainMerge) => boolean | MergeNote
+  /**
+   * Whether the pane a plain `herdr pane send-text|send-keys|run <pane id>` writes into cannot be the herd. Asked only
+   * for that plain form; absent or throwing, every input into a pane asks.
+   */
+  isPaneSafe?: (pane: string) => boolean
+  /**
+   * Whether the agent a plain `herdr agent send-keys|prompt <target>` writes into cannot be the coordinator, whose open
+   * dialog a key would answer. Absent or throwing, every input into an agent asks.
+   */
+  isAgentSafe?: (target: string) => boolean
   /** The aliases and functions of the user's shell, read only when a word at a program position may be one; none by default. */
   shellDefinitions?: () => ShellDefinitions
 }
 
 /**
  * A guarded command the script runs or could run, and the pull request a merge names, when it names one plainly; or
- * the shell alias or function that may run one (`definition`, whose name is then the `command`).
+ * the shell alias or function that may run one (`definition`, whose name is then the `command`). `sole` where it was
+ * the one command of the call, read as written by `gh`; `pane` the pane id an input into a pane names in its plain
+ * form, `input` the words it writes there; `agent` the target an input into an agent names in its plain form.
  */
-/** A guarded command found in the script; `sole` where it was the one command of the call, read as written by `gh`. */
-type Finding = { command: string; merge: PlainMerge | undefined; definition?: ShellDefinitionHit; sole?: boolean }
+type Finding = {
+  command: string
+  merge: PlainMerge | undefined
+  definition?: ShellDefinitionHit
+  sole?: boolean
+  pane?: string
+  input?: string
+  agent?: string
+}
 
 /** What the search looks for: the guarded commands, and the shell definitions that may stand for one of them. */
 type Search = { commands: readonly string[]; definitions: () => ShellDefinitions }
 
-/** The parts of a `gh api` call that decide whether it writes, and where. */
-type ApiCall = { method: Word | undefined; fields: boolean; override: boolean; endpoints: Word[] }
+/**
+ * The parts of a `gh api` call that decide whether it writes, and where: the method it names, whether a header
+ * overrides it, the endpoints, the values of its field options (`fields`), and whether a file or stdin gives the body
+ * (`input`). A field or an input makes the method POST unless one is named.
+ */
+type ApiCall = {
+  method: Word | undefined
+  override: boolean
+  endpoints: Word[]
+  fields: Word[]
+  input: boolean
+}
+
+/**
+ * The parts of a `curl` call that decide whether it writes, and where: the method it names, whether it sends data
+ * (which `-G` turns into a query) or uploads (which `-G` leaves a body), whether a header overrides the method, whether
+ * a config file or an unreadable word may add any option, and the URLs it may reach.
+ */
+type CurlCall = {
+  method: Word | undefined
+  data: boolean
+  upload: boolean
+  get: boolean
+  override: boolean
+  unknown: boolean
+  targets: Word[]
+}
+
+/** An option split into its name and the value attached to it, if any. */
+type SplitOption = { name: string; attached: Word | undefined }
 
 /** The one command whose guard an approval can lift. Every other guarded command asks each time. */
 const MERGE_COMMAND = 'gh pr merge'
@@ -118,6 +176,82 @@ const DANGEROUS_ENDPOINTS = [
   /(^|\/)actions\/(runs|jobs)\/[^/]+\/(rerun|rerun-failed-jobs)\/?$/,
   /(^|\/)git\/refs(\/|$)/,
 ]
+const GRAPHQL_ENDPOINT = /(^|\/)graphql\/?$/
+const API_INPUT_OPTION = '--input'
+/** The GraphQL mutations that do what a dangerous endpoint does: merge, commit, move a ref, rerun the checks. */
+const DANGEROUS_MUTATIONS =
+  /\b(mergePullRequest|mergeBranch|enablePullRequestAutoMerge|enqueuePullRequest|createCommitOnBranch|createRef|updateRefs?|deleteRef|rerequestCheckSuite)\b/
+/** A query field whose text is not in the command: read from a file (`@file`) or nothing but expansions. */
+const UNKNOWN_QUERY = /^query=(@|(\$(\{[^}]*\}|\w+)?)+$)/
+
+/**
+ * `curl` is guarded whatever `guard.commands` says, for a write against the GitHub API: it merges, commits or deploys
+ * as `gh api` does, and no project lists it. A read passes.
+ */
+const CURL_COMMAND = 'curl'
+const GITHUB_API_HOST = 'api.github.com'
+const CURL_READ_METHODS = new Set(['GET', 'HEAD'])
+const CURL_METHOD_OPTIONS = new Set(['-X', '--request'])
+/** Options that send data: POST, unless `-G` turns the data into a query string. */
+const CURL_DATA_OPTIONS = new Set([
+  '-d',
+  '--data',
+  '--data-ascii',
+  '--data-binary',
+  '--data-raw',
+  '--data-urlencode',
+  '--json',
+])
+/** Options that send a body whatever `-G` says: a form is a POST, an upload a PUT. */
+const CURL_UPLOAD_OPTIONS = new Set(['-F', '--form', '--form-string', '-T', '--upload-file'])
+/** Options that turn the data into a query string, or ask for the head only. */
+const CURL_GET_OPTIONS = new Set(['-G', '--get', '-I', '--head'])
+/** A config file can name any option, a method and data among them. */
+const CURL_CONFIG_OPTIONS = new Set(['-K', '--config'])
+const CURL_HEADER_OPTIONS = new Set(['-H', '--header'])
+const CURL_URL_OPTION = '--url'
+/** `--expand-<option>` is `<option>` with variables expanded in its value (curl 8.3). */
+const CURL_EXPAND_PREFIX = '--expand-'
+/**
+ * Every command `decideBashCommand` guards whatever `guard.commands` says, each with its own way to pass:
+ * `isGuardedUse` for curl, `isPaneSafe` and `isAgentSafe` for the inputs into a pane or an agent.
+ */
+const FIXED_COMMANDS: readonly string[] = [...PANE_INPUT_COMMANDS, ...AGENT_INPUT_COMMANDS, CURL_COMMAND]
+/** The short options of curl that take a value: in a group (`-sXPUT`, `-sX PUT`) the rest of the group or the next word. */
+const CURL_SHORT_WITH_VALUE = new Set('AbcCdDeEFHKmoPQrtTuUwxXyYz')
+const CURL_LONG_WITH_VALUE = new Set([
+  ...CURL_METHOD_OPTIONS,
+  ...CURL_DATA_OPTIONS,
+  ...CURL_UPLOAD_OPTIONS,
+  ...CURL_CONFIG_OPTIONS,
+  ...CURL_HEADER_OPTIONS,
+  CURL_URL_OPTION,
+  '--user',
+  '--output',
+  '--cookie',
+  '--cookie-jar',
+  '--write-out',
+  '--max-time',
+  '--connect-timeout',
+  '--retry',
+  '--retry-delay',
+  '--retry-max-time',
+  '--user-agent',
+  '--referer',
+  '--oauth2-bearer',
+  '--variable',
+  '--proxy',
+  '--cacert',
+  '--cert',
+  '--key',
+  '--resolve',
+  '--connect-to',
+  '--limit-rate',
+  '--range',
+  '--dump-header',
+  '--interface',
+])
+
 /** What the fixed end of an endpoint after an expansion may be, when the expansion can stand for the rest of the path. */
 const DANGEROUS_ENDINGS = [
   /(^|\/)merges?\/?$/,
@@ -203,33 +337,57 @@ const isOpaque = ({ value }: Word): boolean => isExpanded(value) && value.replac
 
 const isReadMethod = ({ value }: Word): boolean => !isExpanded(value) && value.toUpperCase() === READ_METHOD
 
-/** An option of `gh api` split into its name and the value attached with `=` (or glued to `-X`), if any. */
-const apiOption = ({ value, literal }: Word): { name: string; attached: Word | undefined } => {
-  if (value.startsWith('-X') && value.length > 2) return { name: '-X', attached: { value: value.slice(2), literal } }
+/** A long option split at its first `=`: `--name=value`. */
+const splitAttached = ({ value, literal }: Word): SplitOption => {
   const at = value.indexOf('=')
   if (at === -1 || !value.startsWith('--')) return { name: value, attached: undefined }
   return { name: value.slice(0, at), attached: { value: value.slice(at + 1), literal } }
 }
 
+/** An option of `gh api` split into its name and the value attached with `=` (or glued to `-X`), if any. */
+const apiOption = (word: Word): SplitOption =>
+  word.value.startsWith('-X') && word.value.length > 2
+    ? { name: '-X', attached: { value: word.value.slice(2), literal: word.literal } }
+    : splitAttached(word)
+
 /** A short body option with its value glued on, as in `-fbody=x`. */
 const isGluedBodyOption = (value: string): boolean => /^-[fF]./.test(value)
 
+/** The value of a field option: attached with `=`, glued to `-f`, or the next word. */
+const fieldValue = (name: string, attached: Word | undefined, next: Word | undefined, word: Word): Word | undefined => {
+  if (attached !== undefined) return attached
+  return isGluedBodyOption(name) ? { value: name.slice(2), literal: word.literal } : next
+}
+
+const isOverrideHeader = (header: Word | undefined): boolean =>
+  header !== undefined && METHOD_OVERRIDE_HEADER.test(header.value)
+
+/** Adds what one option of `gh api` does to the call; `value` is its attached value or the next word. */
+const readApiOption = (call: ApiCall, { name, attached }: SplitOption, word: Word, next: Word | undefined): void => {
+  const value = attached ?? next
+  if (API_METHOD_OPTIONS.has(name)) call.method = value
+  if (name === API_INPUT_OPTION) call.input = true
+  else if (API_BODY_OPTIONS.has(name) || isGluedBodyOption(name)) {
+    const field = fieldValue(name, attached, next, word)
+    if (field !== undefined) call.fields.push(field)
+  }
+  if (HEADER_OPTIONS.has(name) && isOverrideHeader(value)) call.override = true
+}
+
+const takesNextApiWord = ({ name, attached }: SplitOption): boolean =>
+  attached === undefined &&
+  (API_METHOD_OPTIONS.has(name) || API_BODY_OPTIONS.has(name) || API_OPTIONS_WITH_VALUE.has(name))
+
 const readApiCall = (args: Word[]): ApiCall => {
-  const call: ApiCall = { method: undefined, fields: false, override: false, endpoints: [] }
+  const call: ApiCall = { method: undefined, override: false, endpoints: [], fields: [], input: false }
   for (let index = 0; index < args.length; index++) {
     if (!isOption(args[index])) {
       call.endpoints.push(args[index])
       continue
     }
-    const { name, attached } = apiOption(args[index])
-    const takesNext =
-      attached === undefined &&
-      (API_METHOD_OPTIONS.has(name) || API_BODY_OPTIONS.has(name) || API_OPTIONS_WITH_VALUE.has(name))
-    if (API_METHOD_OPTIONS.has(name)) call.method = attached ?? args[index + 1]
-    if (API_BODY_OPTIONS.has(name) || isGluedBodyOption(name)) call.fields = true
-    const header = HEADER_OPTIONS.has(name) ? (attached ?? args[index + 1]) : undefined
-    if (header !== undefined && METHOD_OVERRIDE_HEADER.test(header.value)) call.override = true
-    if (takesNext) index++
+    const option = apiOption(args[index])
+    readApiOption(call, option, args[index], args[index + 1])
+    if (takesNextApiWord(option)) index++
   }
   return call
 }
@@ -263,9 +421,96 @@ const isDangerousEndpoint = ({ value }: Word): boolean => {
  */
 const writesDangerously = (args: Word[]): boolean => {
   if (args.some(isOpaque)) return true
-  const { method, fields, override, endpoints } = readApiCall(args)
-  const writes = override || (method === undefined ? fields : !isReadMethod(method))
-  return writes && endpoints.some(isDangerousEndpoint)
+  const call = readApiCall(args)
+  const { method, fields, input, override, endpoints } = call
+  const writes = override || (method === undefined ? fields.length > 0 || input : !isReadMethod(method))
+  return writes && (endpoints.some(isDangerousEndpoint) || runsDangerousMutation(call))
+}
+
+/**
+ * Whether a call to the GraphQL endpoint may run a mutation that merges, commits, moves a ref or reruns: its query
+ * names one, or its text is not in the command (a file, stdin, an expansion). A query that only reads passes.
+ */
+const runsDangerousMutation = ({ endpoints, fields, input }: ApiCall): boolean =>
+  endpoints.some(({ value }) => GRAPHQL_ENDPOINT.test(normalizedPath(value))) &&
+  (input || fields.some(({ value }) => UNKNOWN_QUERY.test(value) || DANGEROUS_MUTATIONS.test(value)))
+
+const isCurlWriteMethod = ({ value }: Word): boolean =>
+  isExpanded(value) || !CURL_READ_METHODS.has(value.toUpperCase())
+
+/** A curl option's name, with `--expand-<option>` read as `<option>`. */
+const curlOptionName = (name: string): string =>
+  name.startsWith(CURL_EXPAND_PREFIX) ? `--${name.slice(CURL_EXPAND_PREFIX.length)}` : name
+
+/** Adds what one option, with its value, does to the call. */
+const readCurlOption = (call: CurlCall, name: string, value: Word | undefined): void => {
+  if (CURL_METHOD_OPTIONS.has(name)) call.method = value
+  if (CURL_DATA_OPTIONS.has(name)) call.data = true
+  if (CURL_UPLOAD_OPTIONS.has(name)) call.upload = true
+  if (CURL_GET_OPTIONS.has(name)) call.get = true
+  if (CURL_CONFIG_OPTIONS.has(name)) call.unknown = true
+  if (CURL_HEADER_OPTIONS.has(name) && isOverrideHeader(value)) call.override = true
+  if (name === CURL_URL_OPTION && value !== undefined) call.targets.push(value)
+}
+
+/** A group of short options (`-sX PUT`, `-sXPUT`, `-sd x`): the first one that takes a value ends it. */
+const readShortGroup = (call: CurlCall, word: Word, next: Word | undefined): boolean => {
+  const letters = word.value.slice(1)
+  for (let at = 0; at < letters.length; at++) {
+    const name = `-${letters[at]}`
+    if (!CURL_SHORT_WITH_VALUE.has(letters[at])) {
+      readCurlOption(call, name, undefined)
+      continue
+    }
+    const rest = letters.slice(at + 1)
+    readCurlOption(call, name, rest === '' ? next : { value: rest, literal: word.literal })
+    return rest === ''
+  }
+  return false
+}
+
+/**
+ * Reads the words after `curl`. A word made only of expansions where an option may stand could be any of them, so it
+ * counts as unknown; the value of an option (`-H "$AUTH"`) cannot.
+ */
+const readCurlCall = (args: Word[]): CurlCall => {
+  const call: CurlCall = { method: undefined, data: false, upload: false, get: false, override: false, unknown: false, targets: [] }
+  for (let index = 0; index < args.length; index++) {
+    const word = args[index]
+    if (!isOption(word)) {
+      if (isOpaque(word)) call.unknown = true
+      call.targets.push(word)
+      continue
+    }
+    if (!word.value.startsWith('--')) {
+      if (readShortGroup(call, word, args[index + 1])) index++
+      continue
+    }
+    const split = splitAttached(word)
+    const name = curlOptionName(split.name)
+    const takesNext = split.attached === undefined && CURL_LONG_WITH_VALUE.has(name)
+    readCurlOption(call, name, split.attached ?? (takesNext ? args[index + 1] : undefined))
+    if (takesNext) index++
+  }
+  return call
+}
+
+const mentionsGitHubApi = (text: string): boolean => text.toLowerCase().includes(GITHUB_API_HOST)
+
+/** A URL on the GitHub API, or one whose expanded part may be it and whose fixed end is a dangerous endpoint. */
+const mayBeGitHubApi = (word: Word): boolean =>
+  mentionsGitHubApi(word.value) || (isExpanded(word.value) && isDangerousEndpoint(word))
+
+/**
+ * Whether `curl` writes to the GitHub API: a method other than GET or HEAD, named, set by an override header, or
+ * implied by an upload or by data that `-G` does not turn into a query; a config file or an unreadable word may add
+ * any of them.
+ */
+const curlWritesGitHub = (args: Word[]): boolean => {
+  const { method, data, upload, get, override, unknown, targets } = readCurlCall(args)
+  const implied = upload || (data && !get)
+  const writes = unknown || override || (method === undefined ? implied : isCurlWriteMethod(method))
+  return writes && targets.some(mayBeGitHubApi)
 }
 
 /** The words after the first plain `api` behind the program at `index`; all of them when `api` came from an expansion. */
@@ -275,9 +520,15 @@ const apiArguments = (words: SimpleCommand, index: number): Word[] => {
   return at === -1 ? after : after.slice(at + 1)
 }
 
-/** Every guarded command at a program position counts, except a `gh api` call that does not write dangerously. */
-const isGuardedUse = (command: string, words: SimpleCommand, programIndex: number): boolean =>
-  command !== API_COMMAND || writesDangerously(apiArguments(words, programIndex))
+/**
+ * Every guarded command at a program position counts, except a `gh api` call that does not write dangerously and a
+ * `curl` that does not write to the GitHub API.
+ */
+const isGuardedUse = (command: string, words: SimpleCommand, programIndex: number): boolean => {
+  if (command === API_COMMAND) return writesDangerously(apiArguments(words, programIndex))
+  if (command === CURL_COMMAND) return curlWritesGitHub(argumentsOf(words, programIndex))
+  return true
+}
 
 const commandWords = (command: string): string[] => command.split(' ').slice(1)
 
@@ -322,10 +573,61 @@ const argumentsOf = (words: SimpleCommand, index: number): Word[] => {
 const namesCommandWords = (words: SimpleCommand, index: number, command: string): boolean =>
   operandLists(argumentsOf(words, index)).some((operands) => matchesFrom(operands, commandWords(command)))
 
+const isOtherServerOption = ({ value }: Word): boolean =>
+  OTHER_SERVER_OPTIONS.some((option) => value === option || value.startsWith(`${option}=`))
+
+/** A word the shell hands on as written: quoted or plain, without an expansion, a glob or a brace list. */
+const isFixedWord = ({ value, literal }: Word): boolean =>
+  !isExpanded(value) && !(literal && GLOB.test(value)) && !expandsBraces(value)
+
+/**
+ * The pane id of `herdr pane <verb> <pane id> …` written plainly: the first word of its command, the command words and
+ * the pane id unquoted, every word fixed, no option that points at another herdr server. Anything else names no pane
+ * the guard can look up.
+ */
+const plainPaneTarget = (words: SimpleCommand, index: number, command: string): string | undefined => {
+  const expected = command.split(' ')
+  const target = words[expected.length]
+  const plain =
+    index === 0 &&
+    words.every((word) => isFixedWord(word) && !isOtherServerOption(word)) &&
+    words.slice(0, expected.length + 1).every((word) => word.literal) &&
+    expected.every((value, at) => words[at]?.value === value)
+  return plain && target !== undefined && PANE_ID.test(target.value) ? target.value : undefined
+}
+
+/**
+ * The target of `herdr agent <verb> <target> …` written plainly: the first word of its command, the command words and
+ * the target fixed and unquoted, no option that points at another herdr server. The keys or the prompt after it may
+ * be any text, since no shell runs them.
+ */
+const plainAgentTarget = (words: SimpleCommand, index: number, command: string): string | undefined => {
+  const expected = command.split(' ')
+  const target = words[expected.length]
+  const plain =
+    index === 0 &&
+    !words.some(isOtherServerOption) &&
+    words.slice(0, expected.length + 1).every((word) => word.literal && isFixedWord(word)) &&
+    expected.every((value, at) => words[at]?.value === value)
+  return plain && target !== undefined && AGENT_TARGET.test(target.value) ? target.value : undefined
+}
+
+/** The words `herdr pane <verb> <pane id>` writes into the pane, as one line; read only with a plain target. */
+const paneInputOf = (words: SimpleCommand, command: string): string =>
+  words
+    .slice(command.split(' ').length + 1)
+    .map(({ value }) => value)
+    .join(' ')
+
 /** `sole`: the script is this one simple command, written plainly, the only shape an approval can lift. */
 const findingOf = (command: string, words: SimpleCommand, index: number, sole: boolean): Finding | undefined => {
   if (!namesCommandWords(words, index, command) || isReading(words, index, command)) return undefined
   if (!isGuardedUse(command, words, index)) return undefined
+  if (PANE_INPUT_COMMANDS.includes(command)) {
+    const pane = plainPaneTarget(words, index, command)
+    return { command, merge: undefined, pane, input: pane === undefined ? undefined : paneInputOf(words, command) }
+  }
+  if (AGENT_INPUT_COMMANDS.includes(command)) return { command, merge: undefined, agent: plainAgentTarget(words, index, command) }
   const plain = sole && words[index].literal && words[index].value === GH
   return { command, sole: plain, merge: plain ? plainMerge(words.slice(index), commandWords(command)) : undefined }
 }
@@ -336,7 +638,9 @@ const programsOf = (commands: readonly string[]): string[] => [
 
 /** A shell alias or function at the word that may run one of the guarded programs: it hides the words after them. */
 const definitionFinding = (words: SimpleCommand, index: number, { commands, definitions }: Search): Finding[] => {
-  const definition = shellDefinitionAt(words, index, definitions, programsOf(commands))
+  // A definition hides the words after `curl`, so every alias around it would ask; the guard aims at an oversight (D108).
+  const programs = programsOf(commands).filter((program) => program !== CURL_COMMAND)
+  const definition = shellDefinitionAt(words, index, definitions, programs)
   return definition ? [{ command: definition.name, merge: undefined, definition }] : []
 }
 
@@ -346,6 +650,8 @@ const definitionFinding = (words: SimpleCommand, index: number, { commands, defi
  */
 const expandedProgramFindings = (words: SimpleCommand, index: number, { commands }: Search): Finding[] =>
   commands
+    // curl has no command words of its own, so any program from a variable could be it; only a written curl counts
+    .filter((command) => command !== CURL_COMMAND)
     .filter((command) => namesCommandWords(words, index, command) && isGuardedUse(command, words, index))
     .map((command) => ({ command, merge: undefined }))
 
@@ -432,7 +738,56 @@ const callsIn = (script: string, search: Search, top: boolean): Finding[] => {
   return parsed.flatMap((words) => callsInCommand(words, search, sole))
 }
 
-const approvalOf = ({ command, merge }: Finding, policy: GuardPolicy): boolean | MergeNote => {
+/** Whether the policy calls this target safe; no target, no check or a throwing one answer no. */
+const isSafeTarget = (target: string | undefined, isSafe: ((target: string) => boolean) | undefined): boolean => {
+  if (target === undefined || isSafe === undefined) return false
+  try {
+    return isSafe(target)
+  } catch {
+    return false
+  }
+}
+
+const isPaneInput = ({ command, definition }: Finding): boolean =>
+  definition === undefined && PANE_INPUT_COMMANDS.includes(command)
+
+const isAgentInput = ({ command, definition }: Finding): boolean =>
+  definition === undefined && AGENT_INPUT_COMMANDS.includes(command)
+
+/**
+ * The policy for these findings: with more than one input into a pane, none is lifted, since the lookup sees each
+ * pane before the script runs and an earlier input can start the herd a later one clicks into.
+ */
+const policyLiftingOnePaneInput = (findings: readonly Finding[], policy: GuardPolicy): GuardPolicy =>
+  findings.filter(isPaneInput).length > 1 ? { ...policy, isPaneSafe: undefined } : policy
+
+/**
+ * Whether the input into a pane without the herd asks itself: a shell there runs it where no hook sees it. Read as a
+ * script under a policy that lifts nothing, so a guarded command or another input into a pane asks; a herd word, an
+ * expansion or a text the parse cannot read asks too.
+ */
+const inputAsks = (input: string, policy: GuardPolicy): boolean => {
+  // A second line could run an alias the first one defined, and a quoted alias value is not searched.
+  if (input.includes('\n')) return true
+  try {
+    const words = parseShell(input).flat()
+    if (words.some(({ value }) => isExpanded(value) || HERD_WORDS.includes(value))) return true
+  } catch {
+    return true
+  }
+  const liftingNothing: GuardPolicy = {
+    commands: policy.commands,
+    isMergeApproved: () => false,
+    shellDefinitions: policy.shellDefinitions,
+  }
+  return decideBashCommand(input, liftingNothing).kind === 'ask'
+}
+
+const approvalOf = (finding: Finding, policy: GuardPolicy): boolean | MergeNote => {
+  const { command, merge, pane, input = '' } = finding
+  if (isPaneInput(finding))
+    return command === LIFTABLE_PANE_INPUT && isSafeTarget(pane, policy.isPaneSafe) && !inputAsks(input, policy)
+  if (isAgentInput(finding)) return isSafeTarget(finding.agent, policy.isAgentSafe)
   if (command !== MERGE_COMMAND || merge === undefined) return false
   try {
     return policy.isMergeApproved(merge)
@@ -461,8 +816,29 @@ const soleMergeSentence = (findings: Finding[]): string[] => {
   return unchecked.length > 0 ? [PLAIN_MERGE_SENTENCE] : []
 }
 
+/** Why an input into a pane asks: the herd takes its clicks from its input. */
+const paneInputSentence = (commands: string[]): string[] =>
+  commands.length === 0
+    ? []
+    : [
+        `${commands.map((command) => `\`${command}\``).join(' and ')} writes input into a pane; the herd takes clicks from it, so the user confirms it. Only \`${LIFTABLE_PANE_INPUT}\` passes, once per call, into a plain pane id (\`${LIFTABLE_PANE_INPUT} w1:p2 …\` at the start of its command, no wrapper or assignment before it, every word fixed) whose foreground herdr names and which is not the herd, with a command that names no guarded command, no input into a pane and no herd. To end a lane's session, do not type into its pane: send \`herdr agent prompt <lane> /exit\` as a call of its own.`,
+      ]
+
+/** Why an input into an agent asks: a key there can answer the dialog the agent has open, as if the user clicked. */
+const agentInputSentence = (commands: string[]): string[] =>
+  commands.length === 0
+    ? []
+    : [
+        `${commands.map((command) => `\`${command}\``).join(' and ')} writes into an agent and can answer a dialog open there as if the user clicked, so the user confirms it. It passes only into a plain target (\`herdr agent prompt <lane> …\` at the start of its command, the target fixed) whose agent herdr names and which runs in a worktree, not in a main checkout, where the coordinator runs.`,
+      ]
+
+const CURL_SENTENCE = `A \`${CURL_COMMAND}\` that writes to the GitHub API can merge, commit or deploy past the merge guard, so the user confirms it. Merge with a plain \`${MERGE_COMMAND} <number>\`.`
+
 const askBecause = (findings: Finding[], notes: string[], script: string): MergeGuardDecision => {
-  const guarded = findings.filter(({ definition }) => definition === undefined).map(({ command }) => command)
+  const named = findings.filter(({ definition }) => definition === undefined).map(({ command }) => command)
+  const guarded = named.filter((command) => !FIXED_COMMANDS.includes(command))
+  const paneInputs = named.filter((command) => PANE_INPUT_COMMANDS.includes(command))
+  const agentInputs = named.filter((command) => AGENT_INPUT_COMMANDS.includes(command))
   const definitions = [
     ...new Map(
       findings.flatMap(({ definition }) => (definition ? [[definition.name, definition] as const] : [])),
@@ -472,6 +848,9 @@ const askBecause = (findings: Finding[], notes: string[], script: string): Merge
     kind: 'ask',
     reason: [
       ...guardedListSentence([...new Set(guarded)]),
+      ...paneInputSentence([...new Set(paneInputs)]),
+      ...agentInputSentence([...new Set(agentInputs)]),
+      ...(named.includes(CURL_COMMAND) ? [CURL_SENTENCE] : []),
       ...definitions.map(
         (definition) =>
           `${shellDefinitionHint(definition)} It may run a command of guard.commands in .jackherd/config.json, so the user confirms it.`,
@@ -542,19 +921,28 @@ const findingsOrUnreadable = (command: string, search: Search): Finding[] | Shel
  * shell's input, a here-document's data and what `xargs` reads are not searched, and a call that only reads (`--help`,
  * `-h`, `gh … view`, `gh … list`) passes. A script that is exactly `gh pr merge <number>` with merge-method and
  * delete-branch flags and at most one `--match-head-commit <sha>` passes when the user approved it
- * (`isMergeApproved`); any other shape of the merge, and every other guarded command, asks. A script the parse cannot
- * read asks only when a guarded program stands where a command starts.
+ * (`isMergeApproved`); any other shape of the merge, and every other guarded command, asks. The inputs into a pane
+ * (`PANE_INPUT_COMMANDS`) are guarded whatever the list says, since the herd takes clicks from its input: a plain
+ * `herdr pane <verb> <pane id> …` passes when `isPaneSafe` says the pane cannot be the herd, every other shape asks.
+ * The inputs into an agent (`AGENT_INPUT_COMMANDS`) are guarded the same way: a plain `herdr agent <verb> <target> …`
+ * passes when `isAgentSafe` says the agent is not the coordinator. `curl` is guarded whatever the list says and asks
+ * only for a write to the GitHub API (a write method, a body, an upload or a config file); `gh api graphql` asks for
+ * a dangerous mutation (`DANGEROUS_MUTATIONS`) and for a query whose text the command does not show.
+ * A script the parse cannot read asks only when a guarded program stands where a command starts.
  */
 export const decideBashCommand = (command: string, policy: GuardPolicy): MergeGuardDecision => {
-  if (policy.commands.length === 0) return PASS
-  const search = { commands: policy.commands, definitions: policy.shellDefinitions ?? (() => NO_DEFINITIONS) }
+  const commands = [...new Set([...policy.commands, ...FIXED_COMMANDS])]
+  const search = { commands, definitions: policy.shellDefinitions ?? (() => NO_DEFINITIONS) }
   const findings = findingsOrUnreadable(command, search)
   if (findings instanceof ShellParseError) {
-    return namesGuardedProgram(command, policy.commands) ? askUnreadable(findings, command) : PASS
+    // unreadable text with a curl asks only where it names the GitHub API: a curl elsewhere is no merge
+    const searched = mentionsGitHubApi(command) ? commands : commands.filter((each) => each !== CURL_COMMAND)
+    return namesGuardedProgram(command, searched) ? askUnreadable(findings, command) : PASS
   }
   if (findings.length === 0) return PASS
+  const findingsPolicy = policyLiftingOnePaneInput(findings, policy)
   const unapproved = findings
-    .map((finding) => ({ finding, approval: approvalOf(finding, policy) }))
+    .map((finding) => ({ finding, approval: approvalOf(finding, findingsPolicy) }))
     .filter(({ approval }) => approval !== true)
   if (unapproved.length === 0) return PASS
   const notes = unapproved.flatMap(({ approval }) => (typeof approval === 'object' ? [approval.note] : []))

package/kit/hooks/hooks/merge-guard/pane-input.ts

@@ -0,0 +1,61 @@
+/**
+ * Input into a herdr pane. The herd takes its clicks as mouse reports on its own input, and these three commands
+ * write into a pane's input, so an agent could type a click into the herd with them. `herdr agent send-keys` and
+ * `herdr agent prompt` reach only a pane with an agent (`agent_not_found` otherwise, herdr 0.9.0), never the herd; but
+ * a key there answers the dialog open in that agent, and the transcript records it as the user's click (tried in a
+ * throwaway session), so into the coordinator they ask.
+ */
+import { isRecord } from '../shared/json'
+
+/** The commands that write into a pane's input; fixed in the guard, never taken from `guard.commands`. */
+export const PANE_INPUT_COMMANDS: readonly string[] = ['herdr pane send-text', 'herdr pane send-keys', 'herdr pane run']
+
+/** The commands that write into an agent's input; fixed in the guard like the pane inputs. */
+export const AGENT_INPUT_COMMANDS: readonly string[] = ['herdr agent send-keys', 'herdr agent prompt']
+
+/** An agent target as herdr takes it: a pane id or an agent name. */
+export const AGENT_TARGET = /^[A-Za-z0-9][A-Za-z0-9:_.-]{0,63}$/
+
+/**
+ * The one input into a pane that can pass without a question, a whole command line at a time. Text and keys always
+ * ask: the pane's shell keeps a line typed in one call for the next, which no check of a single call sees.
+ */
+export const LIFTABLE_PANE_INPUT = 'herdr pane run'
+
+/**
+ * The words that start the herd after the CLI (`jh herd`, and `plans` as it was called up to 1.6), as
+ * `src/plans/herd-command.ts` names them; a contract test holds the two together.
+ */
+export const HERD_WORDS: readonly string[] = ['herd', 'plans']
+
+/** A pane id as herdr writes it, `w3B:p1`; a pane name is no target of these commands. */
+export const PANE_ID = /^[A-Za-z0-9]+:p[A-Za-z0-9]+$/
+
+/** Options that point the command at another herdr server, where the lookup would not find the pane. */
+export const OTHER_SERVER_OPTIONS: readonly string[] = ['--session', '--remote']
+
+const isArgv = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((word) => typeof word === 'string')
+
+/** The argv of each foreground process in a `herdr pane process-info` answer; undefined for an answer of another shape. */
+export const foregroundOf = (json: string): string[][] | undefined => {
+  try {
+    const answer: unknown = JSON.parse(json)
+    const info = isRecord(answer) && isRecord(answer.result) ? answer.result.process_info : undefined
+    const processes = isRecord(info) ? info.foreground_processes : undefined
+    if (!Array.isArray(processes)) return undefined
+    return processes.flatMap((each) => (isRecord(each) && isArgv(each.argv) ? [each.argv] : []))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether a pane with these foreground processes cannot be the herd: herdr named at least one, and none carries a
+ * herd word after its program. Any doubt (no answer, no process named) counts as the herd. A word `herd` in another
+ * program's arguments asks once too often, never once too few.
+ */
+export const cannotBeHerd = (foreground: readonly (readonly string[])[] | undefined): boolean =>
+  foreground !== undefined &&
+  foreground.length > 0 &&
+  foreground.every((argv) => !argv.slice(1).some((word) => HERD_WORDS.includes(word)))