Follow up Cline upstream updates: required agent description, global modular rules, plugin-based hooks, deprecated .clinerules/.clineignore

[dyoshikawa]

Summary

Cline's SDK/CLI config contract has moved: configured agents now require description (rulesync can emit files Cline refuses to load), global modular rules exist at ~/.cline/rules/ but rulesync drops them, hooks have converged on the documented plugin surface (which invalidates the rationale for closing #1847), .clinerules is literally named DEPRECATED_CONFIG_DIR upstream, and .clineignore is now documented as "deprecate soon".

Upstream baselines at time of research: Cline (VS Code) v4.0.11 (2026-07-24), Cline CLI v3.0.46 (2026-07-19), SDK v0.0.65 (2026-07-19).

Recent Releases

• v4.0.0 (2026-06-26) — release — SDK-backed extension runtime, Cline Plugins, Customize marketplace, MCP file/format migration into shared settings.
• v4.0.1 (2026-06-28) — release — the VS Code extension was rolled back to the pre-SDK (3.89.2) codebase; the SDK migration continues on main. This is why the shipping extension still resolves only the legacy .clinerules paths.
• v4.0.11 (2026-07-24) — release — model additions only.
• cli-v3.0.23 (2026-06-10) — "Added support for configured agents as subagent tools".
• cli-v3.0.25 / v3.0.27 (2026-06-17) — MCP servers inside plugins; cline skill install/manage command.
• Docs 0b0ca9b1 (2026-05-12, PR #10350) — deleted the 514-line file-hooks reference, leaving docs/customization/hooks a stub pointing at /sdk/plugins.
• Docs b919a7e8 (2026-07-21, PR #12410) — .clineignore marked "deprecate soon".
• Docs 9466fcc0 (2026-07-26, PR #12154) — hooks stub retitled "See details under SDK Plugins page".

Upstream path surface at v4.0.11

From resolve*ConfigSearchPaths() in sdk/packages/shared/src/storage/paths.ts (where .clinerules is literally the constant DEPRECATED_CONFIG_DIR) and apps/vscode/src/core/storage/disk.ts:

Surface	SDK / CLI search paths	VS Code (disk.ts)
rules	AGENTS.md, .clinerules/, .cline/rules/, ~/.agents/AGENTS.md, ~/.cline/rules/, ~/Documents/Cline/Rules	.clinerules, AGENTS.md, ~/Documents/Cline/Rules
workflows	.clinerules/workflows, ~/Documents/Cline/Workflows, ~/.cline/workflows, .cline/workflows	.clinerules/workflows, ~/Documents/Cline/Workflows
skills	.clinerules/skills, .cline/skills, .agents/skills, ~/.cline/skills, ~/.agents/skills	same + .claude/skills
agents	.cline/agents, ~/.cline/agents	(none — configured agents are SDK/CLI only)
hooks (files)	~/Documents/Cline/Hooks, ~/.cline/hooks, .clinerules/hooks, .cline/hooks	.clinerules/hooks
plugins	.cline/plugins, ~/.cline/plugins	(not supported)
mcp	~/.cline/data/settings/cline_mcp_settings.json only	extension settings file
permissions	CLINE_COMMAND_PERMISSIONS env var only	env var only

Gaps

1. subagents — Cline's agent frontmatter contract has moved past rulesync's

• Upstream (sdk/packages/core/src/extensions/tools/team/configured-agent-config.ts, v4.0.11; feature landed cli-v3.0.23, 2026-06-10):

  const ConfiguredAgentFrontmatterSchema = z.object({
    name:        z.string().trim().min(1),
    description: z.string().trim().min(1),   // REQUIRED
    tools:       z.union([z.string(), z.array(z.string())]).optional(),
    skills:      z.union([z.string(), z.array(z.string())]).optional(),
    providerId:  z.string().trim().min(1).optional(),
    modelId:     z.string().trim().min(1).optional(),
    maxIterations: z.number().int().positive().optional(),
  })

  isYamlFile() accepts .yml and .yaml. A missing or empty description, or an empty body, makes parseConfiguredAgentConfig throw and the agent is skipped.

• rulesync: project + global. ClineSubagentFrontmatterSchema (src/features/subagents/cline-subagent.ts) declares only name (required) and description (optional), and fromRulesyncSubagent emits whatever came in. Because canonical RulesyncSubagentFrontmatter (src/features/subagents/rulesync-subagent.ts) also has description optional, rulesync will happily write .cline/agents/<name>.yaml with no description — a file Cline refuses to load, with no warning from either side. tools / skills / providerId / modelId / maxIterations are reachable only through the untyped cline: escape section.

2. rules — global modular rules are silently dropped

• Upstream: resolveRulesConfigSearchPaths() (v4.0.11) reads global rules from ~/.cline/rules/ and ~/Documents/Cline/Rules/ in addition to ~/.agents/AGENTS.md; the VS Code extension creates and reads ~/Documents/Cline/Rules (ensureRulesDirectoryExists in disk.ts). Docs: config ("~/.cline/rules/ — Global rules") and cline-rules.
• rulesync: global returns only a root path — ~/.agents/AGENTS.md — and fromRulesyncRule throws for non-root rules in global mode (src/features/rules/cline-rule.ts). The --global dry-run emits one file and drops the four non-root rules that project mode emits, making Cline the only tool in the matrix with a 🌏 rules marker that cannot carry modular global rules.

3. hooks — upstream converged on the plugin surface, which invalidates #1847's close rationale

#1847 was closed not planned on 2026-07-24 because "the two active runtimes still expose incompatible discovery contracts" for file-based hook scripts. That remains true of the file-hook loaders, but the documented surface has moved:

• docs/customization/hooks.mdx lost its entire 514-line file-hook reference on 2026-05-12 (commit 0b0ca9b1) and is now a two-line stub pointing at /sdk/plugins. The docs.cline.bot/features/hooks/hook-reference page cited in Add Cline hooks adapter (executable per-event scripts; needs multi-file output + executable-bit plumbing) #1847's triage no longer exists.
• v4.0.0 (2026-06-26) shipped Cline Plugins as the supported extension mechanism, and the plugins docs document a single unambiguous discovery contract: .cline/plugins/ (project) and ~/.cline/plugins/ (global), .ts/.js modules exporting an AgentPlugin, with an explicit scope warning ("Cline SDK, CLI, and Kanban… not applicable on VSCode and JetBrains Extension for now").
• Hook stages are enumerated at /sdk/plugins: input, runtime_event, session_start, run_start, iteration_start, turn_start, before_agent_start, tool_call_before, tool_call_after, turn_end, stop_error, iteration_end, run_end, session_shutdown, error; plugin objects expose beforeRun / afterRun / beforeModel / afterModel / beforeTool / afterTool / onEvent plus per-hook policies (mode, timeoutMs, retries, failureMode, …).
• rulesync: unsupported — there is no src/features/hooks/cline-hooks.ts (the directory has 20+ other adapters), and the project dry-run emits no hook artifact.
• rulesync already has the exact primitive needed: src/features/hooks/amp-plugin-generator.ts generates a JS/TS plugin module that shells out to the user's canonical hook commands, and src/features/hooks/pi-extension-generator.ts does the same for Pi.

4. rules / commands — the new .cline/* roots are not emitted (forward-looking)

• Upstream: .cline/rules/ (project rules) and .cline/workflows/ (project workflows) are both in the v4.0.11 SDK/CLI search paths, and .cline/rules/ is documented at config. In the SDK path resolver .clinerules is the constant DEPRECATED_CONFIG_DIR.
• rulesync: rules project → .clinerules/ only; commands project → .clinerules/workflows, global → ~/Documents/Cline/Workflows (src/constants/cline-paths.ts, src/features/commands/cline-command.ts).
• Severity note: this is not currently broken. The rolled-back VS Code extension (v4.0.1 shipped the 3.89.2 extension code) reads only .clinerules and .clinerules/workflows, and the SDK/CLI reads both old and new roots — so rulesync's current output is the maximally compatible choice today. The gap is forward-looking.

5. ignore — .clineignore is officially on the way out

• Upstream: the clineignore docs are now titled ".clineignore (deprecate soon)" (docs commit b919a7e8, 2026-07-21) with a warning that it "is not a security or access-control boundary… We're moving away from it as a supported feature." The documented replacement is not a config file but a plugin (sdk/examples/plugins/gitignore-read-files-guard.ts) that enforces via a beforeTool hook and reads .gitignore.
• rulesync: project, straight .clineignore passthrough (src/features/ignore/cline-ignore.ts).

Proposed Follow-up

1. Make description required in ClineSubagentFrontmatterSchema (or fail validation with an explicit message naming Cline's requirement), add typed optional tools / skills / providerId / modelId / maxIterations fields, and accept .yml alongside .yaml on import.
2. Add a global nonRoot path for Cline rules writing ~/.cline/rules/*.md (read by CLI/SDK) and/or ~/Documents/Cline/Rules/*.md (read by both runtimes), keeping ~/.agents/AGENTS.md as the root file.
3. Reopen the hooks question scoped to the plugin surface: add a cline-plugin-generator.ts emitting .cline/plugins/<name>.ts (project) and ~/.cline/plugins/<name>.ts (global), mapping rulesync events onto beforeTool / afterTool / beforeRun / afterRun. This targets one documented contract, needs no executable-bit or multi-file plumbing, and carries no duplicate-execution risk (the file-hook loaders never look at plugins/). Document the VS Code/JetBrains limitation that upstream itself documents.
4. Track the .cline/rules + .cline/workflows migration and switch (or dual-emit with import from both) once the SDK-backed VS Code extension ships as stable. Also consider ~/.cline/workflows for global commands.
5. No code change is forced for .clineignore yet, but the matrix ✅ should be qualified as a deprecated surface. The eventual replacement is the plugin surface from gap 3 — another reason to build the Cline plugin generator.

Minor / not gaps

• mcp scope is correct — sdk/packages/core/src/extensions/mcp/config-loader.ts resolves exclusively through resolveMcpSettingsPath() → ~/.cline/data/settings/cline_mcp_settings.json. docs/cli/cli-reference lists a project .cline/mcp.json and docs/mcp/mcp-overview lists ~/.cline/mcp.json, but neither appears in any v4.0.11 loader, so those doc lines look stale. rulesync's global-only mapping matches the code.
• mcp entry shape — the canonical registration is now nested ({ transport: { type, command|url, … }, disabled, metadata, oauth }); the flat form rulesync writes is explicitly kept as legacy*RegistrationSchema and still parses. isMcpServers (src/types/mcp.ts) is permissive enough that nested entries round-trip untouched.
• rules frontmatter — paths is the only evaluated conditional (rule-conditionals.ts: conditionalEvaluators = { paths }, unknown keys ignored). The alwaysApply / description keys rulesync writes are inert but harmless.
• skills frontmatter — upstream requires exactly name + description (≤1024 chars); ClineSkillFrontmatterSchema matches.
• permissions is an inert artifact — pre-existing design, not an upstream change. CommandPermissionController reads CLINE_COMMAND_PERMISSIONS from the environment and nothing else; no Cline code path loads .cline/command-permissions.json. rulesync knows this (src/features/permissions/cline-permissions.ts tells the user to export CLINE_COMMAND_PERMISSIONS=$(cat .cline/command-permissions.json)), but the README matrix's plain ✅ overstates it. Worth a doc qualification rather than a code change.
• New surfaces with no rulesync feature dimension: cron/scheduled agents (.cline/cron/, ~/.cline/cron/) and agent teams (~/.cline/data/teams/).

Open questions / unconfirmed

• Whether .cline/mcp.json (project) or ~/.cline/mcp.json ever functions: listed in docs/cli/cli-reference and docs/mcp/mcp-overview but absent from every v4.0.11 loader read. Treated as stale documentation.
• Global workflows path: docs say ~/.cline/data/workflows/, paths.ts says ~/.cline/workflows. Code was preferred; the discrepancy is unconfirmed.
• Whether the SDK-backed VS Code extension (reverted in v4.0.1) will re-land with the .cline/rules + .cline/workflows roots — no upstream statement of timing found. This gates gap 4.

References

• https://raw.githubusercontent.com/cline/cline/v4.0.11/sdk/packages/shared/src/storage/paths.ts — the authoritative search-path resolver, including DEPRECATED_CONFIG_DIR (gaps 2, 4).
• https://raw.githubusercontent.com/cline/cline/v4.0.11/sdk/packages/core/src/extensions/tools/team/configured-agent-config.ts — the configured-agent frontmatter schema with required description (gap 1).
• https://raw.githubusercontent.com/cline/cline/v4.0.11/apps/vscode/src/core/storage/disk.ts — VS Code-side paths, used for the comparison table.
• https://raw.githubusercontent.com/cline/cline/v4.0.11/sdk/packages/core/src/extensions/mcp/config-loader.ts — confirms MCP is global-file-only (non-gap).
• https://raw.githubusercontent.com/cline/cline/v4.0.11/apps/vscode/src/core/permissions/CommandPermissionController.ts — confirms permissions are env-var-only (non-gap).
• https://docs.cline.bot/sdk/plugins — the plugin hook stages and per-hook policies (gap 3).
• https://docs.cline.bot/customization/plugins — the plugin discovery contract and its scope warning (gap 3).
• https://docs.cline.bot/customization/clineignore — the "deprecate soon" notice (gap 5).
• https://docs.cline.bot/getting-started/config — documents ~/.cline/rules/ and .cline/rules/ (gaps 2, 4).
• https://github.com/cline/cline/releases/tag/v4.0.1 — the extension rollback that explains why .clinerules is still the compatible choice (gap 4).

[dyoshikawa]

Gaps 1, 2 and 5 are addressed by #2459 (merged). Gaps 3 and 4 stay open here.

Fixed

• Gap 1 (agent contract). The subagent schema now matches Cline's ConfiguredAgentFrontmatterSchema: name/description required non-empty, with tools/skills/providerId/modelId/maxIterations typed. A canonical subagent without a description gets a minimal generated fallback rather than a file Cline refuses to load; a legacy description-less agent file is repaired the same way on import (one old file no longer aborts the whole import run — the subagents import path has no per-file catch). Import scans .yml alongside .yaml, and same-stem .yaml/.yml pairs dedupe instead of silently overwriting each other in the canonical dir.
• Gap 2 (global modular rules). Non-root global rules are emitted to ~/Documents/Cline/Rules/*.md — read by both the VS Code extension and the SDK/CLI — with the same conditional-frontmatter conversion project rules get, and imported back; ~/.agents/AGENTS.md stays the root. Covered by a dedicated global e2e (3-platform).
• Gap 5 (.clineignore). No code change; the docs now qualify the matrix ✅ as a surface upstream titles "deprecate soon" (not a security boundary; plugin enforcement is the replacement direction).

Still open

• Gap 3 — hooks via the plugin surface. Building a cline-plugin-generator.ts (.cline/plugins/<name>.ts project + ~/.cline/plugins/<name>.ts global, mapping canonical events onto beforeTool/afterTool/beforeRun/afterRun) is a full feature following the amp/pi plugin-generator precedent, and — as the issue notes — the same surface is upstream's stated replacement for .clineignore, so it likely deserves one design pass covering both.
• Gap 4 — the .cline/rules + .cline/workflows roots. Deliberately deferred per the issue's own severity note: the rolled-back VS Code extension reads only the legacy .clinerules paths, so today's output is the maximally compatible choice. Re-check when the SDK-backed extension ships as stable.

[dyoshikawa]

Upstream update (re-check on 2026-07-30)

Baseline moved from v4.0.11 to v4.0.12 (2026-07-28), CLI v3.0.47, SDK v0.0.66, plus the new Cline Code desktop app (desktop-v0.0.2, first public 2026-07-22 → desktop-v0.0.7, 2026-07-29). sdk/packages/shared/src/storage/paths.ts is byte-identical between v4.0.11 and v4.0.12, so the path surface tabulated here is still current. Gaps 1, 2 and 5 are confirmed fixed by #2459; no new gaps. Facts below are not yet recorded here.

Newly found releases / changes

• Cline Code desktop app is publicly shipping — desktop releases desktop-v0.0.2 (2026-07-22) through desktop-v0.0.7 (2026-07-29), and the config docs now state config applies "globally across all Cline applications, including IDE, CLI, and SDK". This bears directly on gap 4's deferral: .cline/rules / .cline/workflows now have a shipping GUI consumer even though the VS Code extension still ships the rolled-back pre-SDK reader (.clinerules only). Today's output remains the compatible choice, but the gate is weakening — worth revisiting sooner.
• v4.0.12 / CLI v3.0.47 / SDK v0.0.66 themselves are non-config changes (free-model support, agentic compaction default, connector reconnect, CRLF-preserving edits, models.dev provider list).

Additional facts for the open gaps

• Gap 3 (plugin-based hooks): resolvePluginConfigSearchPaths() at v4.0.12 includes a third global root ~/Documents/Cline/Plugins/ that this issue's path table does not list — fold it into the design pass if a cline-plugin-generator.ts gets built.
• The config docs now document two env overrides: CLINE_DATA_DIR (relocates the whole ~/.cline tree — would relocate the global MCP settings file rulesync writes) and CLINE_HOOKS_DIR (an additional hooks directory). Neither changes generated paths today; relevant only if global-path resolution becomes configurable.
• The "global workflows path" open question is still unresolved upstream: docs say ~/.cline/data/workflows/ while resolveWorkflowsConfigSearchPaths() resolves ~/.cline/workflows; rulesync targets ~/Documents/Cline/Workflows, which is in the resolver, so the discrepancy costs nothing today.

References

• https://github.com/cline/cline/releases — v4.0.12 / CLI v3.0.47 / SDK v0.0.66 / desktop-v0.0.2–v0.0.7 timeline.
• https://docs.cline.bot/getting-started/config — cross-application config statement and the CLINE_DATA_DIR / CLINE_HOOKS_DIR overrides.

[dyoshikawa]

Upstream update (re-check on 2026-08-06)

Newly found releases / changes

Baseline moved again: Cline (VS Code) v4.1.6, CLI v3.0.51 (2026-08-06). The most important delta for this issue's gap 3: file-based hooks are present in the current tree — the docs stub deletion recorded above no longer reflects the shipping surface.

• The docs pages are back/live: https://docs.cline.bot/features/hooks and the CLI reference (cline hook, --hooks-dir, CLINE_HOOKS_DIR).
• Verified in source (current main): VALID_HOOK_TYPES in apps/vscode/src/core/hooks/utils.ts lists TaskStart, TaskResume, TaskCancel, TaskComplete, PreToolUse, PostToolUse, UserPromptSubmit, Notification, PreCompact; the SDK's HookConfigFileName enum adds TaskError and SessionShutdown; discovery paths in sdk/packages/shared/src/storage/paths.ts are project .cline/hooks/ (plus deprecated .clinerules/hooks/) and global ~/.cline/hooks/, ~/Documents/Cline/Hooks/.
• Contract: no JSON config file — each hook is an executable named exactly after the event (extensionless on macOS/Linux, .ps1 on Windows), stdin JSON payload, optional stdout JSON { cancel, contextModification, errorMessage }, 30s default timeout, multi-directory merge (any cancel: true wins).

So the gap-3 framing "hooks have converged on the plugin surface" should be revised: both surfaces exist, and the file-based one is documented and shipping. A rulesync adapter is implementable today as a wrapper-script emitter (mode 0755, one file per event piping the stdin payload into the rulesync command, mapping a blocking result onto {"cancel": true}), in the spirit of amp-plugin-generator.ts / pi-extension-generator.ts. Canonical mapping is clean: sessionStart→TaskStart, preToolUse→PreToolUse, postToolUse→PostToolUse, beforeSubmitPrompt→UserPromptSubmit, preCompact→PreCompact, notification→Notification, afterError→TaskError, sessionEnd→SessionShutdown, taskCompleted→TaskComplete. Constraints: command-type hooks only, and .ps1 variants needed for Windows.

Verified unchanged

• MCP stays global-only in fact: the docs mention .cline/mcp.json, but resolveDefaultMcpSettingsPath() in the SDK resolves only ~/.cline/data/settings/cline_mcp_settings.json; no workspace loader exists in source. Upstream doc inconsistency — worth re-checking on a future pass.
• Permissions: still only the CLINE_COMMAND_PERMISSIONS env-var JSON surface rulesync already writes.

References

• https://cline.bot/blog/cline-v3-36-hooks — original hooks ship (v3.36)
• https://docs.cline.bot/features/hooks — current hooks docs
• https://raw.githubusercontent.com/cline/cline/main/sdk/packages/shared/src/storage/paths.ts — discovery paths incl. hooks dirs

[dyoshikawa]

Shipped the file-based hooks adapter in #2628 — cline is now a hooks target at both project and global scope.

Upstream re-verified from source, because the docs page you linked (docs.cline.bot/features/hooks) now redirects to the SDK plugins page, which documents a different, in-process surface (AgentHooks from @cline/core, stage names like tool_call_before). The file-based surface lives in the VS Code extension:

• https://github.com/cline/cline/blob/main/apps/vscode/src/core/hooks/utils.ts — VALID_HOOK_TYPES, resolveHooksDirectory (<workspace>/.clinerules/hooks/, ~/Documents/Cline/Hooks/) and resolveExistingHookPath (extensionless on Unix, <Event>.ps1 on Windows).
• https://github.com/cline/cline/blob/main/apps/vscode/src/core/hooks/HookProcess.ts — the Unix launch config spawns the script by path through a shell, so it needs mode 0755; the payload arrives on stdin and { cancel, contextModification, errorMessage } is read from stdout.

One correction to the mapping in the comment: TaskError and SessionShutdown are not Cline hook types. VALID_HOOK_TYPES is exactly TaskStart, TaskResume, TaskCancel, TaskComplete, PreToolUse, PostToolUse, UserPromptSubmit, Notification, PreCompact, so afterError and sessionEnd are left unmapped rather than written under names Cline rejects. The remaining seven mappings are implemented as described; TaskResume/TaskCancel have no canonical counterpart.

Notes on the implementation worth knowing: each command is passed to bash -c as a quoted argument (a command containing a comment or quotes cannot break the wrapper) and its syntax is checked first, because an unparseable command would otherwise exit 2 — the cancel code. Control characters are stripped from the JSON result, since a tab in a command's stderr made the whole response unparseable and silently dropped a cancel. Generated scripts carry a rulesync-owned: cline-hooks marker; a script without it is never overwritten (generate warns instead), and dropping the target with --delete removes only the marked ones. Matchers are unsupported and import is generate-only.

The issue's other gaps — global modular rules, the required agent description, and the deprecated .clinerules handling — remain open.

[dyoshikawa]

Two status corrections after a re-check on 2026-08-08:

1. The closing line of the 2026-08-07 comment ("the issue's other gaps — global modular rules, the required agent description, and the deprecated .clinerules handling — remain open") is inaccurate: those are gaps 1, 2 and 5, which landed in PR fix(cline): require the agent description Cline enforces, emit global modular rules, note the clineignore deprecation #2459. Verified in code: CLINE_RULES_GLOBAL_DIR_PATH = join("Documents", "Cline", "Rules") (src/constants/cline-paths.ts:10) and the required non-empty subagent description with repair fallback (src/features/subagents/cline-subagent.ts). Only gap 4 (.cline/rules + .cline/workflows roots) is genuinely open.
2. Gap 4's deferral condition ("re-check when the SDK-backed extension ships as stable") was re-verified today against upstream source and has not fired: the SDK resolver (sdk/packages/shared/src/storage/paths.ts) does include .cline/rules / .cline/workflows, but the shipping VS Code extension (apps/vscode/src/core/context/instructions/user-instructions/cline-rules.ts) still reads only the legacy .clinerules tree. Today's .clinerules output remains the maximally compatible choice; keeping the deferral in place.

[dyoshikawa]

Upstream update (re-check on 2026-08-08)

Newly found releases / changes

• v4.1.0 → v4.1.6 (2026-07-31 → 2026-08-06), cli-v3.0.48 → cli-v3.0.51 (2026-07-31 → 2026-08-06), SDK v0.0.67–v0.0.71, desktop-v0.0.8–v0.0.10 — https://github.com/cline/cline/releases

Additional or changed gaps

• Gap 4's gate has effectively fired: the SDK-based extension is now shipping in the stable channel under a staged rollout. v4.1.0 (2026-07-31) turned the stable extension into a combined A/B VSIX carrying both the legacy pre-SDK extension and the new SDK-based one, with a staged remote rollout starting at 1% that "will become the default for everyone as the rollout completes" and automatic fallback to legacy on activation failure; v4.1.2 added a Legacy/Next indicator and v4.1.3 fixed cross-bundle session/settings-migration bugs, i.e. the rollout is actively progressing. Gap 4 is phrased as "re-check when the SDK-backed extension ships as stable" — it now is, gated by rollout percentage rather than by a release. Suggested reframing: plan dual-emit (.clinerules + .cline/rules, .clinerules/workflows + .cline/workflows), since the legacy bundle stays in the field for the whole rollout window. sdk/packages/shared/src/storage/paths.ts on main still lists both root sets, .clinerules still constant-named DEPRECATED_CONFIG_DIR.

Verified unchanged

• Hook events: VALID_HOOK_TYPES on main is still exactly the nine events the adapter maps; global hooks root ~/Documents/Cline/Hooks unchanged (the SDK also searches ~/.cline/hooks, but the chosen root is the one the VS Code extension reads).
• Gap 3 (plugin-surface hooks): discovery contract unchanged (three roots); cli-v3.0.48 only added ctx.telemetry for plugins.
• Non-gaps this window: desktop-v0.0.10 MCP OAuth lives in the app UI/nested registration shape; v4.1.4 skills-in-slash-menu is presentation only; cli-v3.0.48's single-file .clinerules fix doesn't affect the directory form rulesync emits; plan-mode edit blocking (v4.1.4/cli-v3.0.50) is runtime policy, not the CLINE_COMMAND_PERMISSIONS surface.
• Dry-runs (project 56 files / global 55 files) confirm fix(cline): require the agent description Cline enforces, emit global modular rules, note the clineignore deprecation #2459 (global modular rules) and feat(hooks): add a Cline file-based hooks adapter #2628 (hooks project + global) are live.

References

• https://github.com/cline/cline/releases/tag/v4.1.0 — combined A/B VSIX and staged rollout announcement (gap 4 delta).
• https://github.com/cline/cline/releases — v4.1.x / cli-v3.0.4x–5x timeline.

[dyoshikawa]

Upstream update (re-check on 2026-08-13)

Swept v4.0.x → v4.1.9 and cli-v3.0.15 → cli-v3.0.54 (2026-05 → 2026-08). Gap 4 (the .cline/ roots, now reframed as dual-emit) is unchanged and still the open item. One finding that revisits a correction made here on 2026-08-07:

TaskError and SessionShutdown are real hook events — in the SDK/CLI runtime, not the VS Code one

The #2628 comment corrected an earlier mapping with: "TaskError and SessionShutdown are not Cline hook types. VALID_HOOK_TYPES is exactly TaskStart, TaskResume, TaskCancel, TaskComplete, PreToolUse, PostToolUse, UserPromptSubmit, Notification, PreCompact." That is accurate for the VS Code extension, which is the file apps/vscode/src/core/hooks/utils.ts the comment cites. It is not the whole picture, because Cline has two file-hook runtimes with different event sets.

The SDK/CLI runtime carries its own enum: HookConfigFileName and HOOK_CONFIG_FILE_EVENT_MAP in sdk/packages/core/src/hooks/hook-file-config.ts (verified on main, 2026-08-13) map TaskError → agent_error and SessionShutdown → session_shutdown, and both are documented in sdk/examples/hooks/README.md. So a user running Cline through the CLI or SDK — the runtime the desktop app and cline binary use — has two events the adapter never writes a script for. Current rulesync state: unsupported for those two events, project + global for the other seven.

CLINE_HOOK_EVENTS (src/types/hooks.ts:408) stops at the VS Code list, so canonical afterError and sessionEnd hooks silently produce no Cline output at all. This is not a recent regression — the SDK file predates the visible path history (the 2026-05 repo restructure).

The reason the earlier correction's caution does not apply here: Cline resolves hooks by exact event filename, so a script named for an event a given runtime does not know is simply never invoked. Writing TaskError / SessionShutdown is inert under the VS Code extension rather than an error, exactly as TaskResume / TaskCancel scripts would be inert under a runtime that lacked them. Adding sessionEnd → SessionShutdown and afterError → TaskError to CANONICAL_TO_CLINE_EVENT_NAMES / CLINE_HOOK_EVENTS is therefore safe for both runtimes, and it closes a real hole for CLI/SDK/desktop users.

Worth pairing with gap 4 when that lands, since both are "the shipping VS Code bundle and the SDK bundle disagree, and the SDK side is where the product is heading".

Verified unchanged

Re-checked with no drift against the dry-runs and current source: rules (global AGENTS.md from cli-v3.0.15 is covered by .agents/AGENTS.md; both emitted rule roots still in resolveRulesConfigSearchPaths), MCP (resolveMcpSettingsPath() still resolves only ~/.cline/data/settings/cline_mcp_settings.json with the CLINE_MCP_SETTINGS_PATH override — global-only remains correct, and the docs' .cline/mcp.json mention still has no loader behind it), commands (both emitted workflow dirs still in the search path), subagents (ConfiguredAgentFrontmatterSchema matches field for field; the VS Code "subagents temporarily disabled" note in v4.0.x is a runtime toggle, not a config change), skills, and permissions (the v4.1.x auto-approve rework removed Yolo Mode and defaults command auto-approval off, but the only persisted key is a single boolean toolAutoApprove in global-settings.json — not a rule surface, so the CLINE_COMMAND_PERMISSIONS env-var JSON stays the whole story).

TaskResume / TaskCancel remain deliberately unmapped — they have no canonical counterpart.

References

• https://github.com/cline/cline/blob/main/sdk/packages/core/src/hooks/hook-file-config.ts — HookConfigFileName / HOOK_CONFIG_FILE_EVENT_MAP, the SDK/CLI event set including TaskError and SessionShutdown
• https://github.com/cline/cline/blob/main/sdk/examples/hooks/README.md — the same two events documented for SDK/CLI users
• https://github.com/cline/cline/blob/main/apps/vscode/src/core/hooks/utils.ts — the narrower VS Code VALID_HOOK_TYPES, for contrast