feat(init): allow exactly the installed CLI in each agent's permission file

[theCodeDrift]

Stack (root → tip):

• feat(cli): releases pin their own version, and init names stale CI pins #509
  • ➡️ feat(init): allow exactly the installed CLI in each agent's permission file #510 (you are here)
    • feat(init): one .agents row that names the detected harnesses #511

Tip of a two-PR stack that merges forward, stacked on #509. It delivers the second half of pinned-cli-permissions and archives the change.

What init writes, for each harness it installs the skill into, in the wizard and in --no-interactive:

Harness	File	Rule
Claude Code	.claude/settings.json	permissions.allow: Bash(<inv> *)
Cursor editor	.cursor/permissions.json	terminalAllowlist: <inv>
Cursor CLI	.cursor/cli.json	Shell(npx:<spec>), Shell(npx:<spec> *)
OpenCode	existing opencode.json[c] (root or .opencode/), else .opencode/opencode.json	object form: key appended last; array form: entry inserted first
Codex	.codex/rules/taskless.rules, only when .agents/ is selected and Codex is detected	prefix_rule(pattern = ["npx","<spec>"], decision = "allow")

Every other harness, including everything that reads .agents/skills, gets no rule and falls back to per-command approval in the skill.

Guarantees

• Narrow rules. Every rule uses its harness's word-bounded form, so @0.13.0 never matches @0.13.01. The Codex form was checked with codex execpolicy check.
• Upgrades replace only Taskless's own rule. install.permissions in the manifest records exactly what was written, so the upgrade swaps that entry. A rule the user wrote, even one for Taskless, is never touched.
• Files Taskless created are cleaned up. Once one holds nothing else, it is deleted. A file that existed before is never deleted.
• Some files are left alone and reported. That covers a file that denies the command, or that holds a rule which would override ours in OpenCode's last-match-wins form. It also covers a file that doesn't parse, and a Codex rules file Taskless didn't write.
• Edits keep the file as it was. Indentation and comments survive, through jsonc-parser (new bundled devDependency, already in the lockfile). Entries are placed by hand, because the library's formatter reflowed lines: a user's trailing comment ended up describing our entry. Removals are computed from the parse tree, because the library's removal left a stray quote after an inline insert. Every hand-placed edit is checked to parse back to the value it wrote, and falls back to the formatter if it doesn't.

Announced edits

• Each file gets an Edited <file> or Created <file> line, then a green ALLOW: line per rule added and a red REMOVE: line per old rule taken out. A skipped file gets a yellow SKIPPED: line with the reason.
• The labels carry the meaning without color.
• The wizard previews these lines in its summary step and asks before writing.
• init --json carries them under permissions.

Skill and recipe

• The preflight says the install usually allows the command already, and spells the Claude rule Bash(<inv> *).
• Where a harness can only allow a whole tool, such as Crush, the agent offers only per-command approval.
• The init recipe documents permissions and goes to topic v8.

The changeset at the bottom of the stack grows to describe this PR. Typecheck, lint, and all 2329 CLI tests pass.

Verified against the real build in scratch projects:

• Claude settings kept their 4-space indent and other keys.
• An OpenCode .jsonc kept its comments, with the rule placed after the "*": "ask" catch-all.
• Inline and block-style lists both stayed valid.
• The Cursor and Codex files were created, and the manifest recorded each rule.

Not verified by hand: Cursor CLI's Shell(npx:<args> *) glob, specifically whether * crosses / in file arguments. The docs leave it open.

[theCodeDrift]

@claude /review

[github-actions]

Claude finished @theCodeDrift's task in 6m 57s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contains no review threads and no prior review summaries; its only comments entry is the @claude /review trigger comment itself. This is therefore the first substantive review of this PR — nothing to mark as already-addressed.

• Read .prior-review.json (no prior threads/reviews)
• Fetch PR diff and metadata (gh pr diff 510, gh pr view --json ...)
• Review packages/cli/src/install/permissions.ts
• Review packages/cli/src/commands/init.ts, wizard changes
• Review tests
• Review OpenSpec/changeset/skill doc changes
• Post final review

---

[New] Likely type error: manifest.install = install doesn't typecheck

packages/cli/src/install/permissions.ts:647-658 (writeRecords):

async function writeRecords(cwd: string, records: Records): Promise<void> {
  const directory = join(cwd, ".taskless");
  const { manifest, raw } = await readManifest(directory);
  const install: Record<string, unknown> = { ...manifest.install };
  if (Object.keys(records).length === 0) {
    delete install.permissions;
  } else {
    install.permissions = records;
  }
  manifest.install = install;   // <-- line 656
  await writeManifest(directory, manifest, raw);
}

TasklessInstallManifest (packages/cli/src/filesystem/manifest.ts) is declared as:

export interface TasklessInstallTarget { skills?: string[]; commands?: string[]; mode?: "canonical" | "reference"; }
export interface TasklessInstallManifest {
  cliVersion?: string;
  targets?: Record<string, TasklessInstallTarget>;
  onboarded?: boolean;
}

— it has no permissions field and no index signature. install is explicitly typed Record<string, unknown>, and assigning that back to manifest.install (typed TasklessInstallManifest | undefined) requires every declared property of the target (cliVersion, targets, onboarded) to be satisfiable from the source's index signature, i.e. unknown assignable to string | undefined / Record<string, TasklessInstallTarget> | undefined / boolean | undefined. That doesn't hold, so this assignment should be rejected by tsc --noEmit under this repo's config (and the PR description says pnpm typecheck passes).

Contrast with the existing, working pattern in packages/cli/src/install/state.ts:112-113:

const previousInstall = manifest.install ?? {};
manifest.install = { ...previousInstall, ...toInstallManifest(state) };

That assignment never introduces an explicit Record<string, unknown> annotation, so the spread's inferred type stays structurally compatible with TasklessInstallManifest (TS infers the merge's type from the two typed operands, not from a widened annotation) — it happens to still carry any actual permissions key at runtime (since object spread copies all own enumerable properties, typed or not), it just never needs to assert that back into the narrower type the way writeRecords does.

The straightforward fix is to add permissions?: Record<string, { rules: string[]; created: boolean }> (or equivalent) to TasklessInstallManifest, so writeRecords can build a properly-typed TasklessInstallManifest instead of casting through Record<string, unknown>. Worth double-checking locally with pnpm typecheck before merge — if CI's Validate run turns up green despite this, I'd want to understand why, since the reasoning above seems solid from the type declarations as they currently stand in this tree.

Everything else looks solid

• The harness-specific rules()/edit()/owns() implementations for Claude Code, Cursor (editor + CLI), OpenCode (object and array forms), and Codex all match the OpenSpec table and are backed by targeted tests (word-boundary matching, deny detection, malformed-file refusal, upgrade swap, user-owned-rule preservation, empty-file cleanup, comment/formatting preservation).
• globToRegExp/coversAny/claudeDenies/cursorCliDenies correctly treat a trailing " *" as matching "no args too," which is the right reading for deny-rule coverage and is exercised by tests.
• The hand-placed JSON insertion/removal logic (placeBySibling, remove) is intricate but is verified against the value it just wrote (holds) with a fallback to the library formatter, and the removal logic correctly preserves separator commas regardless of position (first/middle/last element) — traced through by hand against the multi-line/comment test cases and it holds up.
• syncPermissions's two-phase wizard flow (write: false preview, then write: true after applyInstallPlan) re-reads previous records fresh on each call via readRecords, so it isn't vulnerable to the preview/apply ordering going stale.
• The manifest-key handling in syncPermissions (HARNESSES.find((h) => h.owns(file))) only recognizes exact, fixed canonical paths, so a manifest hand-edited with unusual keys can't be used to make the installer read/write outside the project.
• OpenSpec deltas here are all ## ADDED Requirements, so the "MODIFIED must restate in full" trap from CLAUDE.md doesn't apply.
• Changeset bump (patch) is correct for a 0.y.z package per this repo's convention, even though this adds new surface.

No other correctness, security, or test-coverage issues found in the new permission-writing logic, the wizard/summary integration, or the doc/spec/skill updates.

Branch: feat/install-permissions

[github-actions]

[New] manifest.install = install; assigns a Record<string, unknown> to a property typed TasklessInstallManifest | undefined (cliVersion?: string; targets?: ...; onboarded?: boolean; in filesystem/manifest.ts, no index signature and no permissions field). That direction of assignment requires every declared property of the target to be satisfiable from the source's unknown index signature, which doesn't hold — this should fail tsc --noEmit/pnpm typecheck as written.

Compare with install/state.ts:112-113, which merges { ...previousInstall, ...toInstallManifest(state) } without ever widening through an explicit Record<string, unknown> annotation, so it stays structurally assignable.

Suggest adding permissions?: Record<string, { rules: string[]; created: boolean }> to TasklessInstallManifest so this function can build a properly-typed value instead of casting through Record<string, unknown>.

[theCodeDrift]

Re: @github-actions — "Likely type error: manifest.install = install doesn't typecheck"
#510 (comment)

It does typecheck (tsc --noEmit passes, CI included): every property of TasklessInstallManifest is optional, so a Record<string, unknown> is assignable to it. The underlying point is fair, though. permissions was untyped in the manifest model, which forced casts on both read and write. df696d3 adds permissions?: Record<string, TasklessPermissionRecord> to TasklessInstallManifest and drops the casts. readRecords still validates the value field by field, since the manifest is hand-editable.

— AI Coding Agent