Skip to content

ADFA-3570 | Add the Shell Hooks plugin - #162

Draft
davidschachterADFA wants to merge 25 commits into
mainfrom
feature/ADFA-3570
Draft

davidschachterADFA wants to merge 25 commits into
mainfrom
feature/ADFA-3570

Conversation

@davidschachterADFA

@davidschachterADFA davidschachterADFA commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

ADFA-3570

Draft until appdevforall/CodeOnTheGo#2242 merges. This plugin uses the plugin-API listeners that PR adds (since 26.47). CI here compiles against the committed libs/, so it fails until the "Update libs from CodeOnTheGo" workflow refreshes libs/ from stage. I built and tested locally against jars from that branch; they are not committed. At runtime the plugin still loads on an older IDE: only project-opened, project-closed and file-saved are missing there.

Adds Shell Hooks (org.appdevforall.shellhooks), so IT staff can wire Code on the Go into existing workflows with shell scripts instead of writing a plugin.

What it does

Executable scripts in ~/.config/codeonthego/hooks/ run when the IDE reaches each integration point. The layout is git-hooks style: <hook>, then <hook>.d/* in name order. Values arrive in $* as an argument list, never pasted into a shell string, along with COGO_HOOK, COGO_PROJECT_DIR, COGO_HOOKS_DIR, COGO_HOOK_SCRIPT, COGO_HOOK_SOURCE and COGO_IDE_VERSION. A script runs in COGO_PROJECT_DIR, or in HOME when that is empty (for example ide-started, or an action run with no project).

Hook Fired by $*
ide-started once per IDE launch, the first time Shell Hooks starts with hooks on none; COGO_PROJECT_DIR is empty
project-opened / project-closed ProjectLifecycleListener (new) project folder
file-opened / file-closed FileOpenExtension file
file-activated FileChangeListener, debounced 500 ms file, or empty
file-saved FileSaveListener (new) file
build-started / build-succeeded / build-failed BuildStatusListener; a project sync is a Gradle build too failed: the IDE's failure message, such as BUILD FAILED in 12s

Scripts in hooks/actions/ show up as "Run <name>" on a file's tab menu and file-tree long-press (files only), and run in the visible Terminal with $1 = the file.

Hooks are notifications: none can stop a build or a save.

Security

The threat model, from Hal's comment on the ticket:

  • Off by default. The plugin needs system.commands, filesystem.read and filesystem.write (it writes sample scripts into the user's home).

  • Global hooks live in the user's own home folder, so they carry the same trust as typing in the Terminal.

  • Project hooks (<project>/.codeonthego/hooks/) are a separate switch, also off by default. Each script runs only after the user reads it in a Review dialog and trusts that exact content.

    • Approval is keyed on project, relative path and SHA-256. An edited or new script waits for review again, and trust can be revoked per project.
    • Project scripts need no executable bit: shared storage, where the default projects folder lives, blocks it.
  • Trusted scripts run from a private copy of the bytes that were hashed, so the file cannot be swapped between check and run. Copies no trust entry refers to are pruned on activation.

  • What review protects against, and what it doesn't (the docs say this plainly):

    • It protects against scripts that arrive with a project: a cloned repo, AI-agent edits, or a plugin that can only write project files.
    • It cannot stop a plugin that has system.commands or writes files in-process. Such a plugin can already write the global hooks folder or the trust store, so install only plugins you trust.
  • Only plain project scripts can be trusted. A script can be reviewed only if it is:

    • at most 64 KB
    • printable ASCII and newlines only: no tabs, carriage returns or other bytes
    • no line over 100 characters, and none ending in a space
    • named with letters, digits, ., _, - and / only, with no part starting with .

    Anything else is listed as "Can't be reviewed: <reason>", e.g. "line 3, column 1: a tab". It has no Review button and never runs.

    • Reviews found scripts that read as comments but ran a command: a non-breaking space, a carriage return, a long run of spaces hidden by soft wrap, and a tab ending a <<- heredoc. Every one of them breaks this rule.
    • The rule is checked when listing, when trusting and on every run, so an approval stored for other bytes never runs.
    • Global hooks are not limited by it.
  • Review dialog: numbered lines in monospace. Every row a line wraps onto is marked ↳, so a wrap can't pass for a new line. Names the project chose (its folder, paths in the run log) show any other character, including tab and newline, as <U+XXXX>.

  • Plain text is not safe to skim. Review shows every byte, but a plain script can still mislead through shell parsing. The dialog and docs say that reviewing is reading code, and name the tricks: a backslash that joins a # line, a here-document that ends at an unexpected line, and command substitution in here-document text.

    • A best-effort check, not a guarantee. It judges each line on its own and marks the line ! if it contains <<, a backtick or $(, or ends in \. It marks those wherever they appear, comments and strings included, and lists the line numbers by kind above the script. Messages say "may", and none claims where a here-document ends or whether it is quoted. Nothing carries from one line to the next, so no earlier line can blind it. It doesn't cover other tricks such as an alias, IFS or a function named like a builtin, and the dialog says a line without a mark can still do anything.
    • An earlier, smarter version tracked quotes and here-documents. A review showed ordinary code could blind it and some here-documents made it state the wrong end line, so it was replaced before being pushed.
  • What trust doesn't cover: files the hook runs from the project, such as ./scripts/setup.sh, and config that tools read on their own: .git/config (core.fsmonitor), Gradle and npm settings. The dialog and docs say so.

  • Reading, checking and trusting happen off the main thread. The pending list shows at most 50 scripts.

  • No shell injection: headless hooks get their values as argv. The Terminal action is a command line with every value single-quoted, unit-tested against ', $(), backticks and newlines.

  • Hooks run with the app's full access, including the network.

How it runs

  • One queue runs scripts one at a time, which keeps the plugin under the host's 3-command limit. The queue holds up to 64 events and drops the oldest when full. Events run in the order they reach the plugin.
  • Each script has a timeout: 60 s by default, 1-3600 s configurable, and invalid input is rejected rather than clamped.
    • When Termux's GNU timeout exists, the wrapper runs the script under it as a child, so programs the script started are stopped with it at the limit.
    • If the IDE force-kills the wrapper (disable, unload, update), a watchdog stops the script's whole process group within a few seconds of the kill. On the test phone, a script's processes were gone 10 to 25 seconds after tapping Disable; the docs say "within about half a minute", and the rest of the delay wasn't traced. It signals timeout only while that process ID still belongs to timeout.
    • Without timeout, the script runs under setsid in its own session, so a script that signals its own process group (trap 'kill 0' EXIT) can't signal Code on the Go. Actions in the Terminal stay in its foreground group, so Ctrl-C still reaches them.
    • Under timeout a script's stdin is /dev/null.
    • A run counts as timed out only once it reached its limit, so an early exit 124 is a plain failure.
    • Output collected up to the timeout is kept.
    • Under timeout, the script's stdout and stderr go to files in TMPDIR, deleted once open, and are printed when it ends. The host waits for its pipes to close, so otherwise a job left running with a bare & held the run open until the limit and it was recorded as timed out. A run that is stopped loses its output. Without a writable TMPDIR, or without timeout, output goes straight through as before.
    • A script runs in COGO_PROJECT_DIR, or in HOME when that is empty or no longer a folder.
  • Headless commands get no termux-exec, so a bundled POSIX sh wrapper does it instead. A shebang under /bin, /usr/bin or /usr/local/bin resolves in $PREFIX/bin; any other interpreter path runs as written; a script with no shebang runs with bash.

Testing

  • testDebugUnitTest passes 254 tests, none skipped, covering:
    • argv and environment mapping with hostile names
    • quoting
    • trust store and pruning
    • queue order, drop-oldest and timeouts
    • discovery, including the executable-bit rules
    • the plain-script rule, one test per rule with its exact reason, and every trick the reviews found
    • the resolver and trust store refusing a script that isn't plain, and one pending entry for a project reached through a symlink
    • the size cap, including a file whose reported length is wrong
    • the <U+XXXX> reveal of names
    • the line checks: every trick from the reviews that uses the marked syntax is marked on its line, the other tricks are listed as known unmarked, every line of up to 4 characters is checked against the rule, no line changes how later lines are marked, and an ordinary script gets no marks
    • once-per-launch ide-started
    • timeout parsing, and a host error that keeps the script's output
    • IdeCommandRunner's output drain, against a fake host
    • once-per-launch ide-started, via the logic activate() uses
    • the wrapper under /bin/sh, dash, bash and busybox ash: a process-group timeout, a force-killed wrapper, a normal run that leaves nothing behind, setsid without timeout, a watchdog that holds no copy of the IDE's output pipe, a watchdog that signals neither a process that isn't timeout nor a sleep it has already reaped, a job left running with a bare & that no longer holds the output open, the fallback without a writable TMPDIR, output files deleted while the script runs, and a missing project folder
    • HookRunners.create, which activate() uses, wiring in the timeout check
    • an action getting the same variables as a hook
    • the Hooks tab's rows: their order, the pending cap, and what DiffUtil does in four cases: a finished hook on a full log (one insert, one remove, nothing rebound), a trusted script, a changed script, and the master switch
  • 67 guards were each reverted or broken to confirm a test fails: 30 before the plain-script rule, 21 for it, 7 for the line checks, 5 for the watchdog, name and dot-name guards, and 4 for the round 8 nitpick fixes.
  • Seven independent reviews, each by a fresh agent with none of the author's context. Each finding was reproduced under dash, bash and busybox before it was fixed, and all of them are fixed:
    • Rounds 1–2: a non-breaking space let a script that reads as comments run a command under bash, and force-killing the wrapper orphaned the script.
    • Round 3: a long run of spaces hidden by soft wrap, and a tab ending a <<- here-document, could each hide a command. This led to the plain-script rule and the numbered, ↳-marked dialog.
    • Round 4: plain ASCII can still mislead through shell parsing, so the docs now say review is code review, and a best-effort line check was added. The same round also found that trust doesn't cover tool config, plus watchdog races.
    • Round 5: a stateful line checker could be blinded or made to state a wrong here-document ending. It was replaced, before being pushed, by the stateless one above.
    • Round 6: the continuation rule was stated too strongly (a blank before \, or \\, joins differently). It is now hedged everywhere.
    • Round 7, on cf91ae4 and a4f896d, with fixes in 85a97a9:
      • With no project, a script ran in the IDE's last project folder. The wrapper now changes to HOME; 8 new wrapper test cases fail without it, under 4 shells.
      • In bash, a backslash ending a line of unquoted here-document text can join two lines into the delimiter, ending the here-document early. The dialog and docs now say so.
      • Eight smaller doc corrections: a project's ide-started never runs, a failed sync runs build-failed, COGO_PROJECT_DIR can name the last project after it closes, and wording.
  • Device check of a78bc1f on the Note 20 Ultra (Android 13, CoGo C-d-1116-0426), with the plugin installed through the Add-ons Manager:
    • An ide-started hook that starts sleep 40 & and exits 0 was recorded as OK in 398 ms. Its stdout and stderr both showed in the Hooks tab, and the job ran on with no wrapper or timeout left.
    • Run under Android's own /system/bin/sh (mksh R59) and piped into cat, as the host reads it, a script with sleep 8 & gave EOF after 8.18 s with the old wrapper and 0.26 s with the new one, with the same output. Without a usable TMPDIR the fallback still waits (8.23 s), as the README says.
    • A missing COGO_PROJECT_DIR ran the script in HOME, and an existing one ran it in that folder. No cogo-hook.* file was left in TMPDIR.
  • Round 8: the pr-review skill on 63e1c17 (review). Its four confirmed findings are fixed in a78bc1f: a bare & job held a run open (IMPORTANT), a missing project folder didn't fall back to HOME, a project named two ways was listed twice for review, and a host error dropped the output. Each new test fails on 63e1c17, or under a mutation of the line it pins. Two of its three nitpicks are fixed in 6cfe241. An action now gets its variables from the same list as a hook, which adds the missing COGO_IDE_VERSION. The Hooks tab is now one RecyclerView with a ListAdapter, so a finished hook binds one row instead of re-inflating every row. The third nitpick is a host change (an interruptible wait and a process-group kill in IdeCommandServiceImpl), with nothing to change here.
  • Old-IDE fallback: a reflection harness loaded the compiled plugin against the pre-26.47 plugin-api.jar. It constructs, activates and deactivates with only the three new hooks missing.
  • assemblePlugin and addons check pass, with no compiler warnings.
  • Device QA on a Samsung Note 20 Ultra, with the host build from CodeOnTheGo#2242 (4fa72b1f1) and this plugin. It was driven over adb against the ticket's Steps to QA at font scale 0.8, 1.0 and 2.0. Details are in the ticket's comment.
    • 21 of 23 scenarios pass. The one not run needs a pre-26.47 host.
    • One fails: file-activated named the tab that was left. That's a host bug, ADFA-7141, fixed in CodeOnTheGo#2248.
    • The Hooks tab's own labels and buttons render tiny, as do other plugins' tabs. That's the host scaling plugin text by the editor's font size (ADFA-4212), which on that phone was pinched to 6.38: ADFA-7142, fixed in CodeOnTheGo#2255.
    • a4f896d fixes the smaller findings. ide-started no longer gets the last project as COGO_PROJECT_DIR, and build-failed's message loses its trailing newline. The docs now say a sync runs the build hooks, and give how long stopping a script on disable really takes.
  • /plugin-review blocked on two clauses, both now fixed or waiting on the IDE release:
    • 6.1 Compatibility: min_ide_version is 26.47, which is not released yet.
    • Manifest: the missing plugin.editor_tabs, now added, along with max_ide_version 26.99 and filesystem.write.
    • Its other findings, and the code review's, are fixed.

Not done

  • On a device, tooltips were not checked, and neither was the older-IDE scenario (it needs a pre-26.47 host).
  • 6cfe241 (the RecyclerView Hooks tab and the action variables) has not been checked on a device yet.
  • The project-opened, project-closed and save hooks of a78bc1f were not re-run on a device: the phone's IDE build (C-d-1116-0426, from stage) does not have CodeOnTheGo#2242's listeners.
  • The Hooks tab's adapter wiring (staying at the top, opening a run, text selection in a recycled row), the Review double-tap guard, the older-IDE guard for actions, the ↳ gutter, the grouped checks, and Trust and Revoke running off the main thread are all in Android classes and have no unit tests.
  • The engine's pending list has no size limit; only the display stops at 50.
  • The wrapper is not tested under mksh (Android's /system/bin/sh). The tests cover /bin/sh, dash, bash and busybox; by decision, not every shell is checked.
  • Settled since the reviews:
    • Shared storage blocks the executable bit (confirmed by the maintainer), so project scripts not needing it is required, not just defensive.
    • The release bootstraps for v7 and v8 both ship GNU coreutils with bin/timeout. I checked them against their published .md5 files, so the process-group timeout applies in production builds.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH

davidschachterADFA and others added 6 commits November 11, 2026 12:13
Build files, manifest, colors, dimens and icons, following Random-XKCD.
Builds with the shared root wrapper, so no per-plugin gradlew.
min_ide_version 26.47: the project and file-save listeners first ship
there. Permissions: system.commands and filesystem.read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
- Hook catalog and the $* each hook passes.
- Discovery, git-hooks style: <hook> then <hook>.d/* in byte order;
  executable files only; samples, dotfiles and backups skipped.
- TrustStore: a project's own hooks run only after the user trusts
  that exact content (project + path + SHA-256). A trusted script runs
  from a private copy of the trusted bytes, so it cannot change between
  the check and the run.
- HookRunner: one script at a time from a bounded queue that drops the
  oldest event, with a per-script timeout. Values travel as argv,
  never through a shell string.
- cogo-hook-run.sh maps a shebang onto $PREFIX/bin as termux-exec
  would, since the IDE's command service does not preload it.
- ShellQuote for the Terminal, which takes a command line.

Tests cover each of these; the wrapper runs under every POSIX shell
on the machine (dash, bash, busybox ash; not mksh).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
- ShellHooksPlugin listens to project open/close, file open/close/
  switch/save and build start/success/failure, and queues each event
  for the runner. Listeners are added in activate() and removed in
  deactivate(). File switches are coalesced to the last one in 500 ms.
- Nothing runs until the user turns hooks on. Project hooks have their
  own switch, also off by default.
- Settings screen: master switch, hooks folder and sample hooks, the
  timeout, a switch per hook, project hooks, and trusted projects with
  Revoke. Heights are minimums, so rows grow with the font scale.
- Hooks tab: recent runs with exit code and output, and project
  scripts awaiting review. Review shows the whole script and trusts
  exactly the bytes shown.
- Actions: scripts in hooks/actions appear as "Run <name>" on a file's
  menu and run in the Terminal, with every value shell-quoted.
- Tooltips on every contributed element, under plugin_<id>.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
- shell-hooks.html: the gallery page. Hook table with $* and the
  environment, folder layout, actions, timeouts and ordering, the
  project-hook trust model and why it exists, architecture and the
  plugin API each hook uses.
- assets/docs/index.html: the in-IDE guide the tooltips link to.
- README.md: the design decisions a maintainer needs.
- Root README: list the plugin.
- SampleHooksTest: samples never run, and each documents its arguments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
From the code review and the plugin review of the first cut:

- Project hooks need no executable bit (shared storage is noexec);
  they run from the private copy the plugin marks executable.
- A project script over 256 KB is never read or run (bounded read),
  and the runner survives an Error while listing scripts.
- The review dialog reads off the main thread, refuses large scripts
  before reading, and shows bidi, zero-width and control characters as
  <U+XXXX> with a warning; trust still keys on the raw bytes.
- The wrapper remaps only /bin, /usr/bin and /usr/local/bin shebangs, as
  termux-exec does, and runs the script under the Terminal's GNU timeout
  so a timeout stops the whole process group. The host gets the limit
  plus 10 s; exit 124/137 is recorded as timed out, with the output the
  run printed.
- The 26.47 listeners live in WorkspaceHooks, created inside a guarded
  block, so on an older IDE the plugin loads without those three hooks.
- ide-started runs once per IDE launch, not on every activate().
- build-failed no longer promises a literal "cancelled".
- Run <action> is offered for files only; an action that cannot start
  shows in the Hooks tab.
- The timeout field stores only valid values and flags the rest.
- The Hooks tab keys rows on a unique run id, sets output only when a
  row is open, and titles build-failed by its message, not a path.
- Stale verified copies are pruned on activation.
- Tooltips on the Back button and the trust dialog; Tier 2 detail for
  the hooks, review and action tooltips; the nohup advice redirects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
- Threat model: project-hook review protects against scripts that
  arrive with a project, not against a plugin that can run commands or
  write files in-process; such a plugin can already change the global
  hooks folder or the trust store.
- Actions do go through the Terminal as a command line, single-quoted.
- Ordering is the order events reach the plugin; timeouts stop the
  script's process group when coreutils timeout is present, and
  disabling the plugin stops only the top process.
- ide-started is once per launch; build-failed's $1 is the IDE's message;
  project scripts need no executable bit; the shebang rule names the
  remapped paths.
- Manifest: plugin.editor_tabs, plugin.max_ide_version 26.99 (the
  repo's common value), and filesystem.write for the sample hooks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
davidschachterADFA and others added 14 commits November 11, 2026 13:35
The IDE queues the event and starts the sync without waiting, so the
docs no longer promise the hook runs first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
… ASCII

The review dialog revealed a fixed list of deceptive characters and
missed others. A no-break space lets bash read `true<NBSP>#` as a
function name, so a project script that reads as two comments ran a
command, and the dialog showed no warning. Now only printable ASCII,
tab, newline and CRLF are shown as they are; every other code point,
supplementary ones included, is shown as <U+XXXX> with a warning. The
dialog title and the pending list reveal the script's path the same way.

The Hooks tab also decodes and reveals off the main thread, ignores
Review taps while a script loads, and forgets a dismissed dialog only
if it is still the current one, so a second tap cannot leak the window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
The wrapper exec'd GNU timeout, so the IDE's SIGKILL on disable, unload
or update killed only timeout and left the script running with no
limit. timeout now runs as the wrapper's child; a watchdog sees the
wrapper gone and sends timeout TERM, which stops the whole group. A
normal run still returns the script's exit status and leaves nothing
running.

Also:
- Exit 124 counts as a timeout only once the run reached its limit, like 137.
- ide-started's decision moves into IdeStartedTrigger, with tests.
- IdeCommandRunner's drain and tail are tested against a fake host.
- "Run <name>" on an IDE without the plugin Terminal service (before
  26.41) records a run that did not start instead of throwing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
- Review shows every character outside plain ASCII as <U+XXXX>.
- Disabling, unloading or updating the plugin stops a running script
  and what it started when timeout is present.
- ide-started runs once per launch, the first time hooks are on; it can
  run later in a launch that started with hooks off.
- Trust covers only the hook's own bytes, not project files it runs.
- Over-limit scripts are listed for review with a refusal; actions need
  the Terminal service from 26.41.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
…ks in review

A backslash before an invisible carriage return, or before a trailing
space or tab, reads as a line continuation, but the shell escapes the
invisible character and runs the next line as its own command. Pure
ASCII, so the Trust dialog showed it as written, with no warning.

- Every carriage return is now shown as <U+000D>, Windows line endings
  included, and every space, tab or CR that ends a line as a code.
- Each code the reveal adds is highlighted, so it cannot be mistaken
  for the same six characters typed in a script; the code view is
  left-to-right and monospace whatever the device's language.
- Every project-controlled name is revealed: the run log's script and
  target, Settings' trusted projects, and the script path, now also
  shown in full in the dialog body rather than only in its title.
- Count strings use plurals.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
…ten wrapper tests

- Exit 124 or 137 counts as a timeout only when the Terminal has
  `timeout` (the wrapper then ran the script under it) and the run
  reached its limit, measured on a monotonic clock: a wall clock set
  back mid-run no longer turns a timeout into a failure, and without
  `timeout` a script's own 124 is its own failure.
- The watchdog is started as `(exec ... >/dev/null; watch ...) &`:
  dash and busybox kept a saved copy of the IDE's stdout open in a
  background function call with redirections.
- The leaves-nothing test reads output on the side and checks for
  leftovers 0.3 s after the wrapper exits, so it fails without the
  wrapper's kill of its watchdog under every shell; a new test kills
  the wrapper while the script ignores TERM (timeout's KILL, -k 5).
- The Terminal service for plugins shipped in 26.42, not 26.41.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
The README, both HTML pages and the Review help now say that carriage
returns and line-ending blanks are revealed along with non-ASCII, and
why. They note that a large script in another alphabet shows as codes
and may be slow to open, an accepted limit, and that actions need the
26.42 Terminal service.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
Each review found another way to make a project script read differently
in the Trust dialog from how a shell runs it: a no-break space, a
backslash before an invisible CR or trailing blank, a long run of spaces
whose soft wrap looks like a new line, a tab where `<<-` tells it from a
space. Instead of displaying each trick, a project script can now be
reviewed, trusted or run only if it is plain:

- at most 64 KB, never read past 64 KB + 1;
- printable ASCII and LF only: no tab, CR, other control or non-ASCII
  byte;
- no line over 100 characters or ending in a space;
- a name of letters, digits, '.', '_', '-' and '/', no part starting
  with '.'.

ScriptReview.assess names the first violation ("line 3, column 12: a
tab"); such a script is listed in the Hooks tab with that reason and no
Review action. HookResolver re-checks the bytes on every run, so an
approval of bytes that cannot be reviewed never runs, and
TrustStore.trust refuses them.

The Trust dialog now shows one numbered row per line in a RecyclerView,
monospace and left-to-right, with the explanation scrolling above; text
that wraps continues under the text column with an empty number column.
The per-character highlighting of the script is gone, and with it the
quadratic span cost. Names the project chose (project folders, a run's
file, an unreviewable script's name, Settings' trusted projects) are
revealed with each code highlighted; an unreadable script's message is
fixed text plus the revealed path, never the exception text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
- The watchdog's TERM trap only sets a flag. It stops its own sleep only
  when TERM interrupted the wait for it (wait returns over 128 with the
  sleep alive), so it never signals a sleep it already reaped. It sends
  TERM to timeout only while /proc/<pid>/comm still reads "timeout".
- Without timeout, a headless run from a shell that does not lead its
  process group runs the script under setsid, preferring
  $PREFIX/bin/setsid (util-linux 2.41.2 in the release bootstraps), so
  `trap 'kill 0' EXIT` cannot signal Code on the Go. Not leading its
  group, setsid does not fork: the script keeps the wrapper's PID. Runs
  whose input is a terminal (actions) keep the Terminal's group, so
  Ctrl-C still reaches them.
- HookRunners.create builds the plugin's runner, so the wiring of
  HookPaths.hasTimeout into it is tested.

Tests: the watchdog holds no copy of the IDE's output (fails under dash
and busybox with the old redirection); a `kill 0` script leaves its
caller's group alone; the script keeps the wrapper's PID and leads its
own session; hasTimeout; a 124 at the limit is TIMED_OUT only with
timeout installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
README, the gallery page, the in-IDE guide and the help text now say
which project scripts can be reviewed and why, that global hooks are
unaffected, how the dialog shows a script, how names are revealed, the
watchdog's stale-PID guards and the setsid fallback. Drops the notes the
rule made obsolete: the 256 KB limit, highlighted codes in the script,
and slow review of large non-Latin scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
…tchdog's nap

A plain script shows every byte but can still read as inert and run a command. ScriptHints is a
best-effort check, not a guarantee: it marks every line that contains <<, a backtick or $(, or
ends in a backslash. Each line is judged on its own, with no quotes, comments or here-documents
tracked, so no line can change how later lines are marked; it marks many harmless lines and misses
every trick of another kind. It never says where a here-document ends or whether it is quoted. The
tests embed every script the fourth and fifth reviews wrote, each marked on the line its trick
needs; list the tricks outside the three kinds (alias, IFS, ${x@P}, a function named [, esac#)
as known unmarked; check every line of up to four characters against the rule; and show that no
opener (an open quote, here-document, comment continuation or (() changes a later line's marks.

The watchdog stops its sleep only when its TERM flag is set, so a sleep killed from outside and
already reaped is never signalled. Names are revealed with tab and newline as <U+XXXX>, so a
folder name cannot add a line to a dialog. New tests: the watchdog's nap and comm guards via a
harness that logs every kill, and approvals stored for unsafe or hidden names never resolving.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
…off the main thread

Every row a script line wraps onto shows ↳ in the number column (LineGutter, drawn at the text's
own baselines), so a wrap never passes for a new line. Rows don't hyphenate and break simply.

Above the script, a best-effort check lists by kind every line ScriptHints marks, with every line
number up to 100 per kind and a count of the rest, and marks each ! beside its number. The title
says a line without a mark can still do anything. The intro names the three tricks, including that
a backslash ending a comment does nothing.

Trust runs off the main thread and cannot be cancelled once started; taking the script off the
pending list happens inside the same block, so closing the tab cannot leave it listed. Revoke and
loading Settings' list of trusted projects, which resolve canonical paths, run off the main thread
too. The Hooks tab lists 50 pending scripts and counts the rest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
…st leaves out

The README, gallery page, in-app guide and help say plainly that plain text shows every byte but
review is reading code, name the tricks the reviews found, and describe the check exactly: it
marks lines with <<, a backtick or $(, or a final backslash, judges each line alone, marks many
harmless lines and misses other tricks, so a line without a mark can still do anything. Trust does
not cover project files the hook runs, nor config tools read by themselves (.git/config's
core.fsmonitor, Gradle and npm files). Also documented: the dot-name rule, the wrap mark, and
that the wrapper is untested under mksh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
An independent review found the dialog and docs stating that a backslash
ending a line of code always joins the next line, so a # starting it is
never a comment. That is false when a blank comes before the backslash
(the joined # starts a word, so it is a comment) and when the backslash
is itself escaped (nothing is joined). Every place now says "usually"
and names both exceptions, the here-document rule no longer claims the
first exactly matching line, and command substitution "can" run.

The help no longer says a dot-named script is listed: discovery skips it.

Settings cancels an older trusted-list reload when Revoke starts a new
one, so a slow read can't show a project that was already revoked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
davidschachterADFA and others added 3 commits November 12, 2026 23:18
Device QA on a Note 20 found four places where the hooks or their docs
were off.

- ide-started gets no COGO_PROJECT_DIR. It fired with the last project
  even when none was open: at launch the IDE's current project is the
  last one opened.
- build-failed's $1 loses the IDE message's trailing newline, and the
  docs give an example (BUILD FAILED in 12s) instead of implying the
  compiler's output.
- The build hooks' docs say that a project sync is a Gradle build too,
  so these hooks run for it.
- Disabling, unloading or updating the plugin stops a running script
  within about half a minute, not "a few seconds": on the phone the
  script's processes were gone 10 to 25 seconds after Disable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
A second review found the wrapper and the docs off in several places.

- The wrapper changed folder only when COGO_PROJECT_DIR was set. The
  host starts it, given no folder, in its current project, which is the
  last one opened even after it closes, so ide-started ran there. With
  COGO_PROJECT_DIR empty the wrapper now changes to HOME (/ without
  one). WrapperScriptTest shows it under every shell it finds.
- In unquoted here-document text a trailing backslash joins lines too,
  and bash can then take two lines (EO\ and F) as the delimiter, ending
  the text early so later lines run. The dialog, its checks, the help
  and the docs now say so, and no longer claim that the line after an
  escaped backslash is a command of its own.
- COGO_PROJECT_DIR is documented as the IDE's current project, which
  can be the last one opened, and empty for ide-started.
- ide-started is global-only: a project's ide-started never runs.
- build-failed also runs for a failed project sync.
- README's watchdog note keeps its few seconds and adds the half
  minute counted from Disable that the user docs promise.
- Only a cancel's build-failed message is in the IDE's language, and
  $1 loses all trailing whitespace, not just the newline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH

@davidschachterADFA davidschachterADFA left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

IMPORTANT

  • .../src/main/assets/cogo-hook-run.sh:38 - a backgrounded job without a redirect keeps the IDE's pipe open: TIMED_OUT, and the queue waits limit + 15 s

MINOR

  • .../src/main/assets/cogo-hook-run.sh:15 - a missing COGO_PROJECT_DIR falls through to the host's directory, not HOME
  • .../shellhooks/engine/HookLog.kt:103 - pending rows match on the raw path, trust on the canonical one
  • .../shellhooks/engine/HookRunner.kt:222 - NOT_STARTED drops the output the host returned

NITPICK - 3 inline, not listed

Dropped nitpick: HookResolver.kt:98 re-reads and re-hashes the verified copy on every run. It costs little at 64 KB per script.

How this was reviewed. Commit 63e1c17 was reviewed with /code-review at high effort, and I checked every finding by reading the code. Two of its findings were wrong and are not posted. A missing project folder does not stop a hook from starting, because CogoProjectProvider returns null for it. And the fallbacks for older IDEs are reachable, because the host never compares min_ide_version; it only checks that it isn't blank.

Scope. This PR depends on appdevforall/CodeOnTheGo#2242 for the host API, and I read the host code at that PR's head (269162aa5). It isn't a GitHub stack, so findings are graded against this PR's head.

Verdict. The computed verdict is REQUEST_CHANGES, because of one confirmed IMPORTANT finding. GitHub allows the author only a COMMENT review on their own PR, so it is posted as a COMMENT. The addons repo has no written approve or request-changes rule (CLAUDE.md has none, and there is no REVIEW.md or CONTRIBUTING.md), so the pr-review default applied. There are no earlier review rounds on this PR.

davidschachterADFA and others added 2 commits November 15, 2026 21:26
Fixes the four findings of the pr-review round on 63e1c17.

- The wrapper sends the script's stdout and stderr to files in TMPDIR,
  deleted once open, and prints them when the script ends. The host waits
  for its pipes to close, so a job left running with a bare `&` held them:
  a script that exited 0 was recorded as timed out after the limit + 15 s
  and the queue waited that long. Without a writable TMPDIR, or without
  GNU timeout, output goes straight through as before.
- A COGO_PROJECT_DIR that is no longer a folder runs the script in HOME,
  not in the folder the host started it in, which can be another project.
- Pending entries are listed under the canonical project folder, the key
  trust uses, so a project the IDE names two ways is listed once and one
  Trust clears it.
- A host error reported as exit -1 keeps the output the script printed.

New tests: a bare `&` job, the TMPDIR fallback and the deleted files (each
in four shells), a missing project folder, a project reached through a
symlink, and a host error with output. Each fails on 63e1c17, or under a
mutation of the line it pins. 246 tests pass; addons check passes. Not
verified on a device.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
…ks tab as a RecyclerView

From the nitpicks on #162.

Actions built their environment by hand, and that copy lacked
COGO_IDE_VERSION, which the help says every script gets.
HookInvocation.actionEnvironment now builds it from the same list as
a hook's environment.

The Hooks tab removed and re-inflated every row (up to 100 runs and 50
pending scripts) on the main thread at every change. It is now one
RecyclerView with a ListAdapter whose rows are keyed on the run's id
and on the pending script's project and path, so a finished hook binds
only its one new row. When a recycled row is bound off the window, its
selectable output loses text selection (Editor.prepareCursorControllers).
The adapter turns selection back on when the row is attached.

Not changed here: the host's uninterruptible wait and its kill of the
top process only. Every IdeCommandService plugin shares those, so the
fix belongs in the host.

Tests: anActionGetsEveryVariableAHookGets, and PanelRowsTest (7), which
covers the row order and the pending cap. It also checks what DiffUtil
does in four cases: a finished hook on a full log (one insert, one
remove, nothing rebound), a trusted script, a changed script, and the
master switch. 254 tests pass. Four mutations each fail a test. Not yet
checked on a device.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZWMkFWJh7CY7P4kCH
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.

1 participant