codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/sdk/examples/hooks/custom-compaction-hook.example.ts

@@ -0,0 +1,246 @@
+/**
+ * Custom Compaction Runtime Hook Example
+ *
+ * Demonstrates message compaction through a plugin runtime hook. The hook runs
+ * in `beforeModel`, estimates request size, preserves the first user message
+ * and recent working context, and replaces older middle history with one
+ * summary message before the provider request.
+ *
+ * Installation:
+ *   cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/hooks/custom-compaction-hook.example.ts --cwd .
+ *
+ * Usage:
+ *   cline -i "Search the codebase for dispatcher usage, then summarize it"
+ *
+ * Note: for most plugin-owned message rewrites, prefer registerMessageBuilder().
+ * This example exists for cases where you specifically need runtime-hook access
+ * to the current request and snapshot.
+ */
+
+import type { AgentPlugin } from "@cline/core";
+import { estimateTokens as estimateTokensFromChars } from "@cline/shared";
+
+type PluginHooks = NonNullable<AgentPlugin["hooks"]>;
+type BeforeModelHook = NonNullable<PluginHooks["beforeModel"]>;
+type BeforeModelContext = Parameters<BeforeModelHook>[0];
+type AgentMessage = BeforeModelContext["request"]["messages"][number];
+type AgentMessagePart = AgentMessage["content"][number];
+
+const MAX_INPUT_TOKENS = 120_000;
+const COMPACT_AT_RATIO = 0.75;
+const PRESERVE_RECENT_TOKENS = 24_000;
+const SUMMARY_PREVIEW_CHARS = 800;
+
+function estimateTokens(text: string): number {
+	return estimateTokensFromChars(text.length);
+}
+
+function preview(text: string, limit = SUMMARY_PREVIEW_CHARS): string {
+	const trimmed = text.trim();
+	if (trimmed.length <= limit) {
+		return trimmed;
+	}
+	return `${trimmed.slice(0, limit).trim()}\n...[${trimmed.length - limit} more chars summarized]`;
+}
+
+function stringifyUnknown(value: unknown): string {
+	if (typeof value === "string") {
+		return value;
+	}
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+function serializePart(message: AgentMessage, part: AgentMessagePart): string {
+	switch (part.type) {
+		case "text":
+			return `[${message.role}]: ${part.text}`;
+		case "reasoning":
+			return `[assistant reasoning]: ${preview(part.text, 300)}`;
+		case "image":
+			return `[${message.role} image]: ${part.mediaType ?? "unknown"}`;
+		case "file":
+			return `[${message.role} file ${part.path}]: ${preview(part.content, 500)}`;
+		case "tool-call":
+			return `[assistant tool call]: ${part.toolName}(${stringifyUnknown(part.input)})`;
+		case "tool-result":
+			return `[tool result ${part.toolName}]: ${preview(stringifyUnknown(part.output), 500)}`;
+	}
+}
+
+function serializeMessage(message: AgentMessage): string {
+	return message.content.map((part) => serializePart(message, part)).join("\n");
+}
+
+function estimateMessageTokens(message: AgentMessage): number {
+	return estimateTokens(serializeMessage(message));
+}
+
+function isTurnStartMessage(message: AgentMessage): boolean {
+	return (
+		message.role === "user" &&
+		message.content.some((part) => part.type === "text")
+	);
+}
+
+function findFirstUserIndex(messages: readonly AgentMessage[]): number {
+	return messages.findIndex(isTurnStartMessage);
+}
+
+function findRecentStartIndex(messages: readonly AgentMessage[]): number {
+	let tokens = 0;
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index];
+		if (!message) {
+			continue;
+		}
+		tokens += estimateMessageTokens(message);
+		if (tokens >= PRESERVE_RECENT_TOKENS) {
+			return index;
+		}
+	}
+	return 0;
+}
+
+function collectToolNames(messages: readonly AgentMessage[]): string[] {
+	const names = new Set<string>();
+	for (const message of messages) {
+		for (const part of message.content) {
+			if (part.type === "tool-call" || part.type === "tool-result") {
+				names.add(part.toolName);
+			}
+		}
+	}
+	return [...names].sort((left, right) => left.localeCompare(right));
+}
+
+function collectTouchedFiles(messages: readonly AgentMessage[]): string[] {
+	const paths = new Set<string>();
+	for (const message of messages) {
+		for (const part of message.content) {
+			if (part.type === "file") {
+				paths.add(part.path);
+			}
+			if (part.type === "tool-call") {
+				for (const value of Object.values(
+					typeof part.input === "object" && part.input !== null
+						? part.input
+						: {},
+				)) {
+					if (typeof value === "string" && value.includes("/")) {
+						paths.add(value);
+					}
+				}
+			}
+		}
+	}
+	return [...paths].sort((left, right) => left.localeCompare(right));
+}
+
+function buildCompactionSummary(
+	compacted: readonly AgentMessage[],
+	tokensBefore: number,
+): AgentMessage {
+	const roleCounts = compacted.reduce<Record<string, number>>(
+		(counts, message) => {
+			counts[message.role] = (counts[message.role] ?? 0) + 1;
+			return counts;
+		},
+		{},
+	);
+	const tools = collectToolNames(compacted);
+	const files = collectTouchedFiles(compacted);
+	const highlights = compacted
+		.map(serializeMessage)
+		.map((line) => preview(line, 500))
+		.slice(-6);
+
+	return {
+		id: `hook_compaction_${Date.now()}`,
+		role: "user",
+		createdAt: Date.now(),
+		metadata: {
+			kind: "example_hook_compaction_summary",
+			tokensBefore,
+			messagesCompacted: compacted.length,
+		},
+		content: [
+			{
+				type: "text",
+				text: `Context summary:
+
+## Compacted Range
+- Messages compacted: ${compacted.length}
+- Estimated tokens before compaction: ${tokensBefore}
+- Roles: ${Object.entries(roleCounts)
+					.map(([role, count]) => `${role}=${count}`)
+					.join(", ")}
+
+## Tool Activity
+${tools.length > 0 ? tools.map((tool) => `- ${tool}`).join("\n") : "- none"}
+
+## Files Mentioned
+${files.length > 0 ? files.map((path) => `- ${path}`).join("\n") : "- none"}
+
+## Recent Highlights From Compacted History
+${highlights.length > 0 ? highlights.map((item) => `- ${item}`).join("\n") : "- none"}
+
+Continue from this summary plus the preserved recent messages below.`,
+			},
+		],
+	};
+}
+
+const plugin: AgentPlugin = {
+	name: "custom-compaction-before-model-hook",
+	manifest: {
+		capabilities: ["hooks"],
+	},
+
+	hooks: {
+		beforeModel({ request }) {
+			const messages = request.messages;
+			const totalTokens = messages.reduce(
+				(total, message) => total + estimateMessageTokens(message),
+				0,
+			);
+			if (totalTokens < MAX_INPUT_TOKENS * COMPACT_AT_RATIO) {
+				return undefined;
+			}
+
+			const firstUserIndex = findFirstUserIndex(messages);
+			if (firstUserIndex < 0) {
+				return undefined;
+			}
+
+			const recentStartIndex = Math.max(
+				firstUserIndex + 1,
+				findRecentStartIndex(messages),
+			);
+			if (recentStartIndex <= firstUserIndex + 1) {
+				return undefined;
+			}
+
+			const prefix = messages.slice(0, firstUserIndex + 1);
+			const compacted = messages.slice(firstUserIndex + 1, recentStartIndex);
+			const recent = messages.slice(recentStartIndex);
+			if (compacted.length === 0) {
+				return undefined;
+			}
+
+			return {
+				messages: [
+					...prefix,
+					buildCompactionSummary(compacted, totalTokens),
+					...recent,
+				],
+			};
+		},
+	},
+};
+
+export { plugin };
+export default plugin;

codna/agent-core/vendor/cline/sdk/examples/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "examples",
+	"description": "Example apps for the Cline SDK",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"clean": "rm -rf node_modules dist"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.10"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@cline/core": "workspace:*"
+	}
+}

codna/agent-core/vendor/cline/sdk/examples/plugins/README.md

@@ -0,0 +1,203 @@
+# Cline Plugin Examples
+
+A plugin is a single file (or directory) that extends any Cline agent — CLI, Kanban, VS Code, JetBrains, or anything built on the Core SDK. Drop one in, get new tools, hooks, providers, or message rewriters everywhere.
+
+What a plugin can do:
+
+- **Register tools** — give the agent new capabilities it can call
+- **Hook into the lifecycle** — observe or steer execution at key points
+- **Rewrite provider messages** — custom compaction, redaction, context shaping
+- **Emit automation events** — push normalized events into the runtime
+
+## Examples
+
+| Example | What it shows | What it does |
+| ------- | ------------- | ------------ |
+| [weather-metrics.ts](./weather-metrics.ts) | Tool registration + lifecycle metrics hooks. Best starting point. | Adds a mock `get_weather` tool and logs run/tool metrics, workspace git context, token usage, and cost. It also demonstrates blocking `git push` on protected branches from a `beforeTool` hook. |
+| [mac-notify.ts](./mac-notify.ts) | macOS Notification Center alert via `afterRun` | Sends a native macOS notification when a run completes successfully, using the final output text or iteration count as the notification body. Non-macOS hosts no-op. |
+| [custom-compaction.ts](./custom-compaction.ts) | Provider-message compaction via `registerMessageBuilder` | Rewrites oversized provider-bound message history by preserving the first user message and recent context, then replacing older middle history with a structured summary of roles, tools, files, and highlights. |
+| [background-terminal.ts](./background-terminal.ts) | Detached shell jobs with persisted logs and session steering | Registers `start_background_command`, `get_background_command`, and `delete_background_command` so agents can launch long-running shell commands, poll stdout/stderr tails, clean up job metadata, and receive completion summaries as steer messages. |
+| [automation-events.ts](./automation-events.ts) | Plugin-emitted automation events | Registers a normalized `local.plugin_event` automation event type and, when `CLINE_LOCAL_EVENT_INTERVAL_MS` is set, periodically emits demo events into Cline automation. |
+| [gitignore-read-files-guard.ts](./gitignore-read-files-guard.ts) | Runtime hook policy for workspace `.gitignore` boundaries | Uses `beforeTool` to inspect `read_files`, `editor`, and `apply_patch` requests and skips them when target paths match workspace `.gitignore` rules, preventing ignored files from being read or modified. |
+| [env-blocker.ts](./env-blocker.ts) | Deterministic secret protection via `beforeTool` | Uses `beforeTool` to block `read_files` and `run_commands` (e.g. `cat .env`) calls that read `.env` secret files, while leaving `.env.example`/`.env.sample`/`.env.template` readable. A hard guarantee where an AGENTS.md rule is only a suggestion. |
+| [web-search.ts](./web-search.ts) | `web_search` tool backed by an Exa API key | Adds a `web_search` tool that queries Exa for current public web results, with optional result limits, domain filters, recency windows, and country localization. Requires `EXA_API_KEY`. |
+| [openrouter-provider.ts](./openrouter-provider.ts) | Custom model provider via `registerProvider` | Registers an OpenAI-compatible model provider (pointed at OpenRouter) plus its model catalog so the agent can run inference against it. Swap the base URL, API key env var, and models to add any OpenAI-compatible endpoint Cline does not bundle. Requires `OPENROUTER_API_KEY`. |
+| [typescript-lsp/](./typescript-lsp/) | `goto_definition` tool powered by the TypeScript Language Service | Adds `goto_definition(file, line)` for TypeScript/JavaScript projects. It loads the target project’s own TypeScript version, finds identifiers on a line, and resolves definitions through imports, re-exports, aliases, and other language-service semantics. |
+| [agents-squad/](./agents-squad/) | Multi-agent team — spin up subagents with their own models and personalities | Adds tools for starting, messaging, polling, and coordinating background subagents. It includes bundled agent presets, skill discovery/loading, and a shared handoff store for passing notes between subagents in the same conversation. |
+
+The runtime-hook variant of compaction lives in [../hooks/custom-compaction-hook.example.ts](../hooks/custom-compaction-hook.example.ts).
+
+## Try it with the CLI
+
+The CLI auto-discovers plugins from `.cline/plugins` in the workspace, `~/.cline/plugins`, and the system Plugins folder. Use `cline plugin install` for local files, GitHub file URLs, package directories, git repos, and npm packages:
+
+```bash
+cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/weather-metrics.ts --cwd .
+cline -i "What's the weather like in Tokyo and Paris?"
+```
+
+Swap the GitHub URL for any other single-file example.
+
+To block file access for paths ignored by workspace `.gitignore` files:
+
+```bash
+cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/gitignore-read-files-guard.ts --cwd .
+cline -i "Read the ignored .env file"
+```
+
+The guard uses the `beforeTool` runtime hook. When a `read_files`, `editor`, or `apply_patch` call targets an ignored workspace file, the hook returns `{ skip: true }`, so the tool result records a policy error and the file is not accessed.
+
+For a plugin that lives in a directory (with its own `package.json`), use `cline plugin install`:
+
+```bash
+cline plugin install ./examples/plugins/agents-squad
+```
+
+To add web search through a normal plugin tool:
+
+```bash
+cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/web-search.ts --cwd .
+
+export EXA_API_KEY=...
+export OPENROUTER_API_KEY=...
+
+cline auth --provider openrouter --apikey "$OPENROUTER_API_KEY" --modelid anthropic/claude-sonnet-4.6
+cline -P openrouter -m anthropic/claude-sonnet-4.6 "Search the web for recent Bun release notes, then fetch the most relevant page"
+```
+
+The plugin registers `web_search`, which returns normalized search results from
+Exa. It is intentionally separate from `fetch_web_content`: use `web_search` to
+discover relevant URLs, then use `fetch_web_content` when the agent needs to
+inspect a specific page. `EXA_API_KEY` only authenticates the search backend;
+the CLI still needs a normal model provider key or saved provider auth for
+inference.
+
+## Run a demo directly
+
+```bash
+ANTHROPIC_API_KEY=sk-... bun run examples/plugins/weather-metrics.ts
+```
+
+## Anatomy of a plugin
+
+```ts
+import type { AgentPlugin } from "@cline/core";
+import { createTool } from "@cline/core";
+
+const myPlugin: AgentPlugin = {
+  name: "my-plugin",
+
+  manifest: {
+    capabilities: ["tools", "hooks"],
+  },
+
+  setup(api, ctx) {
+    api.registerTool(createTool({ /* ... */ }));
+  },
+
+  hooks: {
+    beforeRun({ snapshot }) { /* ... */ },
+    afterRun({ result }) { /* ... */ },
+  },
+};
+
+export default myPlugin;
+```
+
+Pass it to the SDK:
+
+```ts
+import plugin from "./my-plugin";
+import { ClineCore } from "@cline/core";
+
+const host = await ClineCore.create({ backendMode: "local" });
+await host.start({
+  config: {
+    providerId: "anthropic",
+    modelId: "claude-sonnet-4-6",
+    apiKey: process.env.ANTHROPIC_API_KEY ?? "",
+    cwd: process.cwd(),
+    enableTools: true,
+    systemPrompt: "You are a helpful assistant.",
+    extensions: [plugin],
+  },
+  prompt: "What's the weather like in Tokyo and Paris?",
+  interactive: false,
+});
+```
+
+## Capabilities
+
+Declare what the plugin uses in `manifest.capabilities`. Each one unlocks one part of the `api` passed to `setup()`:
+
+| Capability         | What it unlocks |
+| ------------------ | --------------- |
+| `tools`            | `api.registerTool()` |
+| `commands`         | `api.registerCommand()` |
+| `rules`            | `api.registerRule()` |
+| `skills`           | bundled skills discovered from the plugin package |
+| `providers`        | `api.registerProvider()` |
+| `messageBuilders`  | `api.registerMessageBuilder()` |
+| `automationEvents` | `api.registerAutomationEventType()` and `ctx.automation?.ingestEvent()` |
+| `hooks`            | runtime lifecycle callbacks (see below) |
+
+The setup `ctx` may include `session`, `client`, `user`, `workspaceInfo`, `automation`, `logger`, and `telemetry` depending on the host. See [`automation-events.ts`](./automation-events.ts) for an end-to-end example.
+
+## Runtime hooks
+
+Hooks are typed, in-process callbacks on the same hook layer as `@cline/agents`. They run inside the agent loop with full type information.
+
+| Hook          | When it fires |
+| ------------- | ------------- |
+| `beforeRun`   | before the runtime loop starts |
+| `afterRun`    | after the runtime loop finishes |
+| `beforeModel` | before each model request |
+| `afterModel`  | after each model response, before tool execution |
+| `beforeTool`  | before each tool execution |
+| `afterTool`   | after each tool execution |
+| `onEvent`     | every `AgentRuntimeEvent` emitted by the runtime |
+
+`beforeRun` and `afterRun` wrap one `run()` / `continue()` invocation — in an interactive session, that's one user turn. `afterRun` is the right place for completion notifications, but it also fires on aborted and failed runs, so check `result.status === "completed"` if you only want successes.
+
+### Plugin hooks vs file hooks
+
+File hooks are external scripts in `.cline/hooks` that the runtime invokes with serialized JSON payloads. Plugin runtime hooks are typed callbacks inside the agent loop. Core adapts file hooks onto the runtime hook layer.
+
+| File hook | File event | Backed by runtime hook |
+| --------- | ---------- | ---------------------- |
+| `TaskStart` | `agent_start` | `beforeRun` |
+| `TaskResume` | `agent_resume` | `beforeRun` with resume context |
+| `UserPromptSubmit` | `prompt_submit` | `beforeRun` with prompt context |
+| `PreToolUse` | `tool_call` | `beforeTool` |
+| `PostToolUse` | `tool_result` | `afterTool` |
+| `TaskComplete` | `agent_end` | `afterRun` (completed) |
+| `TaskError` | `agent_error` | `afterRun` (failed) |
+| `TaskCancel` | `agent_abort` | `afterRun` or session shutdown |
+| `SessionShutdown` | `session_shutdown` | session cleanup |
+
+Use **file hooks** for user- or workspace-configured scripts. Use **plugin runtime hooks** when the behavior belongs to a reusable extension and needs typed access to the runtime.
+
+## Custom message compaction
+
+Use `registerMessageBuilder` when a plugin needs to rewrite the provider-bound message list before the model call. Builders run after runtime messages are converted into SDK message blocks and before core's built-in safety pass — so provider-safe normalization is still the final word.
+
+| Example | Extension point | Best for |
+| ------- | --------------- | -------- |
+| [`custom-compaction.ts`](./custom-compaction.ts) | `api.registerMessageBuilder()` | reusable, plugin-owned compaction policies |
+| [`../hooks/custom-compaction-hook.example.ts`](../hooks/custom-compaction-hook.example.ts) | `hooks.beforeModel` runtime hook | logic that needs runtime hook context or direct request mutation |
+
+Prefer the message-builder version for normal compaction. It runs in the core message pipeline before the built-in safety builder, multiple builders run in registration order, and the final pass enforces provider-safe truncation.
+
+Reach for `beforeModel` only when you need the runtime snapshot or want to mutate the runtime request object itself.
+
+## Background terminal plugin
+
+[`background-terminal.ts`](./background-terminal.ts) registers three tools for long-running shell jobs:
+
+| Tool | Purpose |
+| ---- | ------- |
+| `start_background_command` | starts a detached shell command, returns a job id immediately, captures stdout/stderr under Cline's data directory |
+| `get_background_command` | reads job status plus recent stdout/stderr tails |
+| `delete_background_command` | deletes saved job metadata, optionally deletes captured logs |
+
+When `notifyParent` is true (the default), the plugin emits a `steer_message` through the host bridge after the command exits, pushing a completion summary back into the active session — so the agent can react to long-running commands without blocking the original tool call.

codna/agent-core/vendor/cline/sdk/examples/plugins/agents-squad/README.md

@@ -0,0 +1,122 @@
+# Agent Squad Plugin
+
+Spin up background subagents from any Cline SDK agent. Each subagent runs as its own session with its own provider, model, and system prompt — useful for parallel recon, planning, implementation, and review.
+
+## Quick start
+
+```ts
+import { ClineCore } from "@cline/core";
+
+const cline = await ClineCore.create({ backendMode: "auto" });
+
+await cline.start({
+  config: {
+    providerId: "cline",
+    modelId: "anthropic/claude-sonnet-4.6",
+    cwd: process.cwd(),
+    enableTools: true,
+    systemPrompt: "You are a coding assistant with access to subagents.",
+    pluginPaths: ["./examples/plugins/agents-squad"],
+  },
+  prompt: "Use subagents to investigate and refactor this repo.",
+  interactive: true,
+});
+```
+
+Pass the plugin **directory** as the path. The loader reads `package.json` and discovers entry points from the `cline.plugins` field.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `start_subagent` | Start a subagent in the background and return a session ID immediately. |
+| `message_subagent` | Send a follow-up message to a running subagent. |
+| `get_subagent` | Poll status, output, or error for a subagent session. |
+| `list_agent_presets` | List bundled, global, and project agent presets. |
+| `list_skills` / `get_skill` | Discover and load loadable skill instructions. |
+| `save_handoff` / `read_handoff` | Share text between subagents in the same conversation. |
+
+`start_subagent` accepts `preset` and/or `instructions`. When `preset` is omitted it defaults to `phantom` (configurable via `CLINE_SUBAGENT_DEFAULT_PRESET`).
+
+## Bundled agents
+
+| Agent | Model | Role |
+|---|---|---|
+| `phantom` | `google/gemini-3-flash-preview` | Fast codebase recon — maps structure, surfaces conventions, never implements. |
+| `oracle` | `anthropic/claude-opus-4.6` | Opinionated planning — challenges assumptions and produces execution-ready plans. |
+| `anvil` | `anthropic/claude-opus-4.6` | Surgical implementation — reads before writing, stays in scope, reports exact diffs. |
+| `inquisitor` | `openai/gpt-5.5` | Adversarial review — finds bugs, severity-ranks findings. |
+
+### Typical orchestration
+
+```
+parent → start_subagent(preset: "phantom", task: "Map the auth module")
+       → phantom: save_handoff("auth/recon.md", ...)
+       → start_subagent(preset: "oracle", task: "Plan refactor from auth/recon.md")
+       → oracle: save_handoff("auth/plan.md", ...)
+       → start_subagent(preset: "anvil", task: "Execute auth/plan.md")
+       → start_subagent(preset: "inquisitor", task: "Review anvil's changes")
+```
+
+## Custom agents and skills
+
+Drop a Markdown file with YAML frontmatter into one of these directories. Project overrides global, global overrides bundled (by `name`).
+
+| Kind | Bundled | Global | Project |
+|---|---|---|---|
+| Agents | `agents/` next to `index.ts` | `~/.cline/data/settings/agents/` | `<cwd>/.cline/agents/` |
+| Skills | `skills/` next to `index.ts` | `~/.cline/data/settings/skills/` | `<cwd>/.cline/skills/` |
+
+Agent file:
+
+```markdown
+---
+name: my-agent
+description: One-line description shown in list_agent_presets
+providerId: cline
+modelId: anthropic/claude-sonnet-4.6
+cwd: ./src
+maxIterations: 25
+---
+
+You are a specialized agent that...
+```
+
+Skill file:
+
+```markdown
+---
+name: my-skill
+description: What this skill teaches
+---
+
+When performing this task, follow these steps...
+```
+
+Skills are reusable instructions any agent can pull in at runtime via `get_skill`. Bundled skills include `code-review`, `test-generation`, `refactoring`, `debugging`, `api-design`, `migration`, and `documentation`.
+
+## Handoff store
+
+Subagents in the same conversation share a small file store, scoped to the conversation ID:
+
+- `save_handoff({ path, content })` — writes a file
+- `read_handoff({ path })` — reads it back
+
+Files live under `~/.cline/data/plugins/subagents/handoffs/<conversationId>/`. Paths are validated to prevent traversal.
+
+## Configuration
+
+All optional. Environment variables override defaults:
+
+| Variable | Default |
+|---|---|
+| `CLINE_SUBAGENT_PROVIDER_ID` | `cline` |
+| `CLINE_SUBAGENT_MODEL_ID` | `anthropic/claude-sonnet-4.6` |
+| `CLINE_SUBAGENT_DEFAULT_PRESET` | `phantom` |
+| `CLINE_SUBAGENTS_BACKEND_MODE` | `auto` (`auto` \| `hub` \| `local`) |
+| `CLINE_SUBAGENT_CWD` | `process.cwd()` |
+| `CLINE_DATA_DIR` | `~/.cline/data` |
+
+## How it works
+
+Each subagent is a full Cline SDK session created via `ClineCore.create(...)`. `start_subagent` resolves the preset, merges any overrides, starts a non-interactive session, and returns the session ID immediately. The first turn runs in the background; when it finishes (or fails) the result is stored and — unless `notifyParent: false` — pushed back to the parent session as a steer message. The parent can also poll with `get_subagent`.

codna/agent-core/vendor/cline/sdk/examples/plugins/agents-squad/agents/anvil.md

@@ -0,0 +1,16 @@
+---
+name: anvil
+description: Surgical implementation agent — makes focused changes, verifies correctness, and reports precise diffs.
+providerId: anthropic
+modelId: claude-opus-4-6
+---
+
+You are a surgical implementation subagent.
+
+Your job is to execute a plan with precision:
+
+1. **Read before writing**: Always read the relevant code before making changes. Never modify what you haven't fully understood.
+2. **Stay in scope**: Make only the changes required by the task. Don't refactor adjacent code, add unsolicited improvements, or touch files outside the blast radius.
+3. **Verify after each change**: After a write, confirm the file is in the expected state. Run type-checks or tests if available and relevant.
+4. **Handle blockers immediately**: If a dependency is missing, a type is wrong, or a test fails, fix the blocker before continuing. Don't proceed with a broken state.
+5. **Report precisely**: When done, report exactly which files changed, what was added/removed/modified, and what (if anything) is left incomplete. No vague summaries.

codna/agent-core/vendor/cline/sdk/examples/plugins/agents-squad/agents/inquisitor.md

@@ -0,0 +1,18 @@
+---
+name: inquisitor
+description: Adversarial review agent — finds bugs, challenges design decisions, and stress-tests assumptions.
+providerId: cline
+modelId: openai/gpt-5.5
+---
+
+You are an adversarial review subagent.
+
+Your job is to stress-test a change or design, not to approve it. Approach every review as if you are responsible for everything that goes wrong after it ships.
+
+1. **Correctness**: Find logic errors, off-by-one bugs, null/undefined gaps, and incorrect assumptions about input shape or ordering.
+2. **Regressions**: Check whether the change could break existing callers, consumers, or tests — especially ones not in the immediate diff.
+3. **Design pressure**: Challenge the design itself. Is this the right abstraction? Does it introduce hidden coupling? Is the complexity justified?
+4. **Missing tests**: Identify scenarios that are untested. Suggest specific test cases, not just "add more tests".
+5. **Security and safety**: Flag anything that touches auth, user input, external data, or shared mutable state.
+
+Severity-rank every finding: **critical** (must fix), **major** (should fix), **minor** (worth noting). Skip praise unless something is genuinely non-obvious and done well.

codna/agent-core/vendor/cline/sdk/examples/plugins/agents-squad/agents/oracle.md

@@ -0,0 +1,18 @@
+---
+name: oracle
+description: Opinionated planner that challenges assumptions, estimates complexity, and produces execution-ready plans.
+providerId: cline
+modelId: anthropic/claude-opus-4.6
+---
+
+You are a planning and estimation subagent with a challenger mindset.
+
+Given a task or requirement:
+
+1. **Challenge the premise**: Before planning, ask whether the stated goal is actually the right goal. Identify hidden assumptions and call them out.
+2. **Compare approaches**: Present 2–3 concrete implementation options with honest tradeoffs. Don't default to the obvious path without justifying it.
+3. **Estimate complexity**: Rate each option by effort (S/M/L/XL), risk, and reversibility. Flag anything that touches shared infrastructure or has outsized blast radius.
+4. **Produce an execution plan**: A numbered, dependency-ordered list of steps the worker agent can follow directly. Include explicit checkpoints and rollback conditions.
+5. **State your assumptions**: List what you're taking as given. If any assumption is wrong, note which steps break.
+
+Be direct and opinionated. A plan with a clear recommendation beats a balanced non-answer.

codna/agent-core/vendor/cline/sdk/examples/plugins/agents-squad/agents/phantom.md

@@ -0,0 +1,17 @@
+---
+name: phantom
+description: Fast reconnaissance agent for codebase discovery, pattern matching, and code archaeology.
+providerId: cline
+modelId: google/gemini-3-flash-preview
+---
+
+You are a reconnaissance and archaeology subagent.
+
+Your job is fast, thorough discovery. When exploring a codebase:
+
+1. **Map structure**: Identify relevant files, entry points, data flow, and API contracts.
+2. **Surface conventions**: Note naming patterns, abstraction layers, and implicit rules the codebase follows.
+3. **Dig for intent**: When something looks odd — a workaround, a TODO, an unexpected abstraction — note it. Explain what it's likely reacting to or compensating for.
+4. **Produce crisp output**: Return a structured summary the parent agent can act on directly. No filler.
+
+Never attempt implementation. Return findings only.