feat(agent): preflight with agent ok before any Taskless command

[theCodeDrift]

A harness can refuse to run the CLI before Taskless says a word. In a real session, Claude Code's auto mode blocked npx @taskless/cli-nightly@<pin> agent onboard because it downloads and runs a package from npm. The block was correct. The trouble is where it landed: onboarding's one consent question lives inside the recipe, so the agent never reached it. It stopped, then improvised an allow rule, npx @taskless/cli-nightly:*, that approves every future nightly rather than the one this project installed.

What changes

• taskless agent ok prints one line, This message confirms you can run Taskless via <invocation>., and exits 0. It is built into agent rather than added as a recipe file, so it carries no template sections or fetch-time directive. It reads and writes nothing, so it is safe to run first in any directory. When the launcher can't be detected it says "via the command you just ran" rather than guessing npx. It emits cli_agent with topic: "ok" and opens the taskless agent index under a new "Preflight:" heading.
• The skill and /tskl run it once per session, before any other Taskless command. On a block, of the preflight or of any later Taskless command, the agent stops and names the exact command and that it comes from npm. It then offers three ways forward: the user approves that exact command in chat, the user runs ! <exact command>, or the agent adds an allow rule for exactly the invocation %(TASKLESS_CLI)s. It is told never to propose a rule that wildcards the package name or version.

The skill body is 131 lines, under its 150-line cap.

Follow-up, outside this change

Claude Code's docs say a chat approval that names the exact action can clear an auto-mode block, and that broad allow rules are dropped on entering auto mode. They don't say whether the npm download block can be cleared by approval at all, or whether a pinned npx allow rule survives auto mode. A hand test of both under auto mode may justify reordering the remedies the skill offers; that would be its own change. This one is complete and archived.

Checks

pnpm typecheck, pnpm lint, the full @taskless/cli suite (2303 tests), and openspec validate --specs --strict all pass on the rebased branch.

[theCodeDrift]

@claude /review

[github-actions]

Claude finished @theCodeDrift's task in 2m 45s —— View job

---

Review: feat(agent): preflight with agent ok before any Taskless command

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contains no prior review threads, reviews, or top-level comments beyond the trigger comment itself, so this is the first review of this PR — every finding below is new.

• Read .prior-review.json
• Gather PR diff and metadata
• Review changed files (agent.ts, both tests, SKILL.md, tskl.md, OpenSpec artifacts)
• Post findings

Overall assessment

The implementation is clean and matches its design doc closely. detectCliInvocation/processLauncherContext are reused rather than re-derived (good — follows the existing convention in onboard.ts/init.ts), the ok branch is placed before recipe lookup and before the "too many arguments" guard interferes with it, the index-rendering changes are a straightforward reorder, and the test coverage in agent-ok.test.ts exercises the detected/unknown-launcher cases, the index row, telemetry, and the no-.taskless/-write guarantee. The skill/tskl prose and the installed-documentation.test.ts addition stay consistent with each other.

Two small things worth a look, neither blocking:

[New] proposal.md's "What Changes" section undercounts the remedies it describes.
openspec/changes/agent-ok-preflight/proposal.md (the bullet under "What Changes") says a blocked preflight "offers two ways forward: the user runs ! <exact command> themselves, or the agent adds an allow rule...". That drops the first remedy — the user approving the exact command in their chat reply — which design.md, both spec files (specs/skill-taskless/spec.md), and the actual prose in skills/taskless/SKILL.md/commands/tskl/tskl.md all describe as the first of three options. Since OpenSpec archiving later folds proposal.md's intent into the historical record, it's worth fixing so the proposal doesn't undercount its own feature relative to the spec and the shipped text.

[New] "No side effects" in design.md is slightly stronger than what ok actually does.
design.md's Decisions section states ok "does not bootstrap .taskless/, read the manifest, or check auth" and must be "safe to run in any directory, first." That's true of the project's .taskless/ directory (confirmed by the does not create .taskless/ test), but ok still calls getTelemetry(cwd) like every other topic, which — unless telemetry is disabled — writes an anonymous ID file under the user's global config dir (~/.config/taskless/anonymous_id) and resolves repository/adoption context (a git subprocess) for the capture. That's shared, pre-existing behavior for every agent topic, not something this PR introduces, and it's handled defensively (telemetry failures are swallowed). It just means the "reads and writes nothing" framing is a bit optimistic for the preflight specifically, since the whole point of putting it first is that it should be safe to run speculatively in an untrusted directory before anything else happens. Not a functional bug — just a doc/behavior mismatch worth a one-line caveat if the intent is to eventually make ok fully side-effect-free.

No correctness, security, or test-adequacy issues found in the agent.ts logic, the index/output reordering, or the new tests.

[theCodeDrift]

Re: @github-actions[bot] — "Claude finished @theCodeDrift's task in 2m 45s — Review: feat(agent): preflight with agent ok…"
#505 (comment)

Both fixed in 9602a88. proposal.md now names all three remedies. The side-effect claim is scoped to project state in design.md, SKILL.md, and the agent.ts comment, and design.md records why ok keeps the telemetry capture: dropping it would lose the preflight-vs-task measurement.

— AI Coding Agent