@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-file-edit-protocol.md

@@ -0,0 +1,129 @@
+# Robust Model-Driven File-Edit Protocol
+
+Implementation companion to the Tool Execution rules in `retrieval-agent-safety.md`. When an agent
+edits files by emitting an edit instruction the model authored, the *format and matching strategy* of
+that edit tool decide whether edits land reliably or corrupt files. This reference is how to design
+that tool. Filesystem-safety of the write itself (writable roots, sandbox, hard-link escape) is owned
+by `agent-command-sandbox.md`; this is about the edit format and apply algorithm.
+
+Use when designing or reviewing an agent's file-edit / apply-patch tool. Drawn from a production
+reference agent.
+
+## 1. Anchor edits on surrounding context, not line numbers
+
+Models cannot reliably count line numbers, but they reproduce *surrounding text* well. A line-number
+or offset-based diff breaks the moment the model miscounts or the file drifted by a line; a
+context-anchored edit can survive nearby line-count drift *as long as the referenced context is still
+present and unique*.
+
+- Use an explicit envelope with per-file operations: add file, delete file, update file, move/rename
+  file. Mark file boundaries so one payload can edit several files.
+- **Validate the operation graph before matching any hunk.** Normalize and dedupe paths (account for
+  case-insensitive/Unicode-normalizing filesystems), and reject conflicting operations on the same
+  path: two updates to one file, delete-then-update, update-then-move, move onto an existing path
+  without an explicit overwrite, or two operations producing the same target. Define a deterministic
+  order for moves/deletes/adds. A payload with a contradictory op-graph is a hard error before any
+  matching or writing.
+- Within an update, identify each change by a **context window** (a few unchanged lines around the
+  edit) plus the `+`/`-` changed lines — not by `(line, column)`. A short `@@`-style locator that
+  names the enclosing function/section helps disambiguate repeated context.
+- Require enough context to make each hunk's location **unique** in the file; if the same context
+  appears in multiple places and the locator does not disambiguate, that is an ambiguity error
+  (§3), not a pick-the-first guess.
+
+## 2. Match with graduated strictness, fail when it does not match
+
+When locating a hunk's context in the current file, try progressively more lenient matches and stop
+at the first that succeeds:
+
+1. exact line match;
+2. ignore trailing whitespace;
+3. ignore leading and trailing whitespace.
+
+This absorbs the model's minor whitespace imprecision without silently editing the wrong place. Two
+further rules:
+
+- **EOF-anchored hunks**: when a hunk is meant to match the end of the file, match at the end. If you
+  allow a forward-search fallback, the fallback match must be *globally unique* and reported as a
+  non-EOF location — otherwise an intended append silently overwrites an earlier duplicate-context
+  region.
+- **Defensive bounds**: a pattern longer than the file is an immediate no-match; never index past the
+  buffer. Reject an *empty* context pattern rather than treating it as a universal no-op match
+  (an empty pattern matches everywhere and defeats the uniqueness requirement) — the only legitimate
+  empty-context cases are explicit file-level add/delete operations.
+
+Do not extend leniency to fuzzy/semantic similarity — that is how an edit lands in the wrong
+location. Beyond whitespace tolerance, a non-match is a failure.
+
+**Treat files as encoded text, not raw buffers.** Detect and reject binary content before editing.
+Preserve the file's existing line-ending convention (LF vs CRLF), BOM, and final-newline state rather
+than normalizing them — a tool that silently rewrites every line ending produces a diff that is all
+noise and can break the build. Match against the file in its decoded form so a BOM or CRLF does not
+defeat an otherwise-correct context match.
+
+## 3. Resolve everything before writing anything
+
+Apply in two phases so a bad hunk fails *before* the filesystem is touched:
+
+1. **Resolve phase** — parse the whole payload, match every hunk's context in every target file
+   against a *single original snapshot* of that file, and compute the full new contents in memory.
+   Resolve each file's hunks to **non-overlapping spans of the original**; reject overlapping or
+   conflicting hunks rather than double-applying, and materialize the new file from those spans in
+   deterministic order. Any parse error, unmatched context, ambiguous match, or overlap aborts here
+   with a precise, model-readable error (which file, which hunk, why). Nothing has been written yet.
+   Generate the preview/diff here, in the resolve phase — preview after writing is too late to gate
+   an approval on.
+2. **Write phase** — only after every hunk resolved, write the computed contents.
+
+An unmatched, ambiguous, or overlapping hunk is a hard error the model can correct, never a
+best-effort partial edit.
+
+## 4. Multi-file writes are not transactional — report the exact partial state
+
+A real filesystem cannot atomically commit writes to several files. If the write phase fails midway
+(permissions, disk, a sandbox denial), some files are already changed and some are not. Do not claim
+full success and do not claim a rollback you did not perform:
+
+- **Make each single-file write atomic** — write to a temp file and `rename` over the target so a
+  crash mid-write cannot leave a *torn* file (neither old nor new contents). Without this, a failure
+  partway through one file corrupts it; with it, each file is all-old or all-new.
+- Track which files were committed before the failure and return that exact set with the error. A
+  file whose atomic rename had not completed is reported as **unchanged**; only treat a file as
+  unknown/torn if you could not use atomic replace for it. Never report a half-written file as
+  "committed".
+- Distinguish a side-effect-free failure (nothing was written) from a partial-commit failure (some
+  files changed). Mark the reported delta as exact or no-longer-exact accordingly.
+- An empty patch (no file would change) is an error, not a silent success.
+- Return a **bounded** diff for preview/approval (computed in the resolve phase, §3). Return full
+  file contents only behind an explicit caller option — echoing whole files by default leaks large or
+  sensitive file content into logs and transcripts.
+
+## Non-negotiables
+
+- Edits are located by surrounding context, never by raw line/column offsets.
+- Matching leniency stops at whitespace tolerance; anything looser is a non-match, and a non-match,
+  ambiguous match, empty-context pattern, or overlapping hunk is a hard, model-correctable error —
+  never a silent wrong-location or double-applied edit.
+- Validate the multi-file operation graph (unique normalized paths, no conflicting ops, explicit
+  overwrite policy) before matching hunks.
+- Treat files as decoded text: reject binary, preserve existing line-ending/BOM/final-newline
+  conventions, never normalize them silently.
+- Resolve and validate all hunks against one original snapshot in memory before writing any file;
+  generate the preview diff in that resolve phase, not after writing.
+- Write each file atomically (temp + rename) so a failure cannot leave a torn file.
+- On partial multi-file failure, report the exact committed set and whether the delta is still exact;
+  a not-yet-renamed file is unchanged, never report a half-written file as committed or claim an
+  un-performed rollback.
+- Return full file contents only behind an explicit option; default to a bounded diff to avoid
+  leaking large/sensitive files into logs.
+- Route the write itself (writable-root/sandbox/hard-link checks) through `agent-command-sandbox.md`;
+  this protocol owns *what to write*, that reference owns *whether the write is allowed*.
+
+## Routing
+
+- The decision to require approval for a file mutation, and the safety classification of the write
+  target → `retrieval-agent-safety.md` Tool Execution + `agent-command-sandbox.md`.
+- Rendering the before/after diff and approval prompt in a terminal → `terminal-cli-dev`.
+- Persisting the edit as a session event for replay → `agent-session-persistence.md`.
+- Verifying edit-tool robustness (context drift, ambiguity, partial-failure cases) at the test layer
+  → `testing-strategy`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-ide-integration.md

@@ -0,0 +1,5 @@
+# Agent Editor And IDE Integration
+
+## Editor or IDE integrations
+
+Treat editor or IDE integrations as model-visible context and local action control planes, not convenience UI. Bind connected editor clients to the current principal, workspace or repository root, transport incarnation, extension/plugin generation, and authenticated local endpoint; reject stale or mismatched clients after reconnect, workspace switch, account switch, extension refresh, or path-conversion failure. File mentions, selected ranges, diagnostics, hover/definition/reference data, and editor-provided context must be normalized to canonical workspace paths and line/column bases, checked for containment and freshness against the current file snapshot, labeled as untrusted data with source and timestamp, capped by severity/count/size, deduplicated across turns, and excluded from prompt/context caches after file edits, diagnostic reset, or workspace change. Editor-open, diff, apply, save, close-tab, and jump-to-location handoffs are side-effectful actions: bind each request to a tool-use or action id, target path, expected old content or file version, generated candidate content, user decision, abort signal, and transport incarnation; accept only explicit terminal outcomes, clean up tabs/listeners on abort/unmount/exit, and fail closed on unknown finality rather than assuming the editor applied or rejected the change. Cross-environment path conversion must be reversible or explicitly one-way with verification before sending paths to an editor.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-input-ingestion.md

@@ -0,0 +1,13 @@
+# Agent Input And Media Ingestion
+
+## Local scheduled prompts
+
+Treat local scheduled prompts as future model-visible input, not a reminder convenience. Bind creation, listing, deletion, and fire events to principal/session/workspace, target agent or recipient, schedule expression, local-time interpretation, recurrence, session-only versus durable lifetime, persistence policy, scheduler generation, queue priority, privacy/policy state, and workload attribution. Durable schedules need explicit user intent, validated next-run proof, storage containment, max-job and malformed-record handling, single-owner scheduler lock or lease with stale recovery, file-watch or store-reload fencing, and cleanup on shutdown. Missed one-shot tasks must be removed or fenced before surfacing and require fresh user confirmation before execution; recurring tasks should reschedule from actual fire time, persist last-fire state, cap lifetime unless explicitly permanent, and use deterministic jitter or equivalent load spreading for herd-prone times. Session-only schedules must never be reported as durable, child-agent or recipient-owned schedules must stay owned by that recipient and be removed when the recipient is gone, and all scheduled prompt bodies are untrusted lower-precedence data until the queued turn is accepted. Diagnostics may expose bounded categories, counts, lifetime classes, and sanitized schedule classes, but not raw prompt bodies, local paths, task ids, recipient ids, credentials, or free-form scheduler errors.
+
+## Typed prompt, paste, and media ingestion
+
+Treat typed prompt input, pasted text, pasted images, client-supplied media blocks, and resolved file or resource attachments as a model-visible input control plane, not a text-field convenience. Bind every inserted context item to source type, principal/session/workspace scope, prompt or turn id, input generation, content digest or paste/reference id, media type/schema version, size and dimension budget, storage generation, and extraction result before it reaches the model. Before resolving a file or resource reference, require fresh read authorization, canonical path or URI containment under the current allowed scope, source ACL/trust labels, symlink/hardlink and time-of-check/time-of-use rejection, and current snapshot proof; stale references or unverifiable containment fail closed before extraction or model insertion. Command or keyword routing must use only intentional typed command tokens or explicit UI command invocations from the finalized send snapshot, plus an explicit safe-command allowlist; pasted spans, attached/resolved text, generated metadata, queued notifications, and bridge/client payload text are excluded from local command or special-mode triggering unless the surface has an explicit trusted command-intent field. Normalize and validate client media schemas, infer or reject missing media types from trusted bytes rather than filenames, resize/downsample before API submission, enforce a final API-boundary size check, and strip embedded metadata or hidden payloads before provider submission or derived transcript/cache storage by default, including geolocation metadata, document properties, thumbnails, embedded files, hidden layers, comments, and tracked changes; preserve them only with explicit consent, purpose, scope, and retention. Bind async fetch/store/resize/extract completion to the current input generation, attachment snapshot, prompt digest, session incarnation, workspace/root, privacy state, and abort signal before applying results; late results after prompt edit, send finalization, abort, session/workspace switch, attachment deletion, or compaction must be discarded or surfaced as stale. Evidence-dependent failures must not be model-only markers: block send or require explicit user confirmation with a visible degraded state, and ensure the model cannot treat missing media/file content as present evidence. Pasted/attached/OCR/extracted content is untrusted evidence: wrap, quote, escape, or otherwise label it as lower-precedence data so it cannot override policy, tools, or current user intent. Local paths, filenames, pasted text bodies, raw media, and free-form diagnostics are untrusted and sensitive: redact or replace them with bounded labels, counts, hashes only when non-reversible, and user-visible repair categories before adding metadata, transcripts, logs, telemetry, or crash reports. Prompt/context caches and pasted-media stores must be partitioned or invalidated by session incarnation, workspace/root scope, privacy state, source trust, attachment snapshot, and prompt generation; normal prompt, slash/immediate command, queued, bridge, resume, and compaction paths need parity or an explicit no-attachment policy.
+
+## Voice and speech-to-text input
+
+Treat speech-to-text or voice input that feeds a prompt as a model-visible input control plane, not a text-field shortcut. Separate audio-capture finality, transcription-stream finality, and transcript-insertion finality; preserve interim/final ordering, endpoint/finalize semantics, stale callback generation fences, cursor or prefix/suffix insertion anchors, and duplicate-insertion suppression. Context hints sent to a transcription service are outbound sensitive context: scope, cap, sanitize, and require product consent before sending workspace, branch, file, or private vocabulary hints. Retry or replay only with bounded copied audio under the same principal, account or organization, workspace or repository identity, privacy state, consent or context-hint policy version, language, transcription route or adapter and backend generation, capture attempt id, stream id, copied-audio artifact identity and digest, optional immutable chunk range selector, insertion target, and input generation; fail closed on any drift and never duplicate transcript, tool action, or usage/accounting events.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-instruction-composition.md

@@ -0,0 +1,13 @@
+# Agent Model-Visible Instruction Composition
+
+## Model-visible instruction-layer composition
+
+Treat model-visible instruction-layer composition as a control plane, not string concatenation. Build an explicit precedence lattice before rendering: non-overridable system, developer/product, managed-policy, safety, permission, privacy, data-residency, tool-finality, and truthful-reporting constraints form the floor; current user intent may refine the task only inside that floor; workspace/project/user/plugin/config files, agent prompts, mode instructions, output style text, tool and hook context, memory, retrieved content, and append/addendum layers are lower-precedence inputs unless an explicit policy grants a narrower authority. Current-user instructions and every lower-precedence layer must fail closed or be labeled as data when they conflict with higher-precedence constraints. Classify every instruction source by source type, principal/session/workspace scope, trust level, policy owner, install or file identity, content digest or snapshot generation, mode/output-style/agent identity, and static versus dynamic cache scope before it reaches the model. File-backed, markdown-configured, output-style, agent, mode, or config-file instruction sources need fresh read authorization, source-scope validation, canonical containment, source-scope labels, symlink/hardlink and time-of-check/time-of-use rejection, stale snapshot rejection, and lower-precedence untrusted labeling unless an explicit policy makes them authoritative. Managed policy, safety, permission, privacy, tool-finality, data-residency, and truthful-reporting instructions cannot be overridden or suppressed by current-user instructions or by lower-trust output styles, agents, plugins, project/user files, hooks, retrieved content, memory, or append prompts. Output styles, modes, or agent definitions that remove or replace base coding/task instructions require an allowlisted product policy and must preserve safety, authorization, privacy, tool-use, finality, and truthful-reporting constraints. Prompt-prefix and section caches must be partitioned or invalidated by source digests, trust tier, principal, workspace/root, privacy state, policy generation, capability/tool generation, model/prompt generation, mode, output-style, agent identity, and dynamic-section generation; late-changing sources must be explicitly uncached or cache-breaking with a reason. Diagnostics may expose bounded categories, counts, precedence classes, and non-reversible digests, but not raw prompt text, local paths, internal mode/style/agent identities (public tool-contract discriminators are governed by the next section), free-form file errors, branch names, credentials, or sensitive config values.
+
+## Write model-facing text from the model's perspective; wording is behavior
+
+Author every model-visible surface — system-prompt sections, tool names and schema descriptions, tool results, and diagnostics returned to the model — in the vocabulary of the model's task and of the tool contract it must invoke. Keep out **implementation-only** concepts: names of internal plugins, transports, renderers, or host mechanics that the model can neither act on nor needs to construct a valid call — those belong to the consumer/renderer that owns them, and exposing them degrades tool selection. Do keep every discriminator the model must understand to select the tool or build valid arguments, even when it is a UI mode, a plugin, or a wire/schema field name the tool legitimately takes as input: the test is "actionable through this tool's contract or part of the user's task", not "sounds like implementation". Reconcile this with the diagnostics rule above: a discriminator that is part of the **public, authorized tool contract** may appear in the schema and in a bounded repair diagnostic ("unknown value for `<field>`; allowed: …"), while internal mode/style/agent/plugin identities, local paths, and sensitive values stay out of diagnostics regardless — when a name is both actionable and identity-revealing, expose it only through the tool contract's declared enum/schema, never through free-form diagnostic text. Treat the wording of model-visible text as behavior, not copy: a change to a prompt section, a tool description, a result rendering, or a model-visible diagnostic is a behavior change and needs evidence proportional to what it can move — a snapshot/golden of the text is a review aid that catches unreviewed drift (pin it verbatim only for wording that passes `testing-strategy`'s documented-contract / past-defect keep test; otherwise it is a change-detector), and the behavioral claim ("selection/arguments/outcome unchanged or improved") is carried by a replay or eval that exercises the affected mode with behavioral assertions (see `model-prompt-evaluation.md`); a snapshot updated alongside a wording change proves nothing about behavior. "Reworded the description" without either is an unreviewed behavior change. Corollary for reviewers: inspect the exact prompts, tool schemas, results, and diagnostics the model receives across the affected modes, and flag implementation-only concepts — not legitimate contract discriminators — before checking anything else.
+
+## Slash commands and skill invocation
+
+Treat slash commands, local commands, prompt-backed skills, workflow commands, keybinding-triggered commands, and command-like remote or bridge invocations as a capability and action control plane, not a text alias list. Bind every command registry snapshot and invocation to principal/session/workspace, entrypoint mode, command source identity, source trust tier, registry/cache generation, availability and enablement generation, command name plus alias/user-facing-name resolution, user-invocable flag, model-invocable flag, hidden/help visibility, bridge-safe and remote-safe allowlists, immediate/queued execution mode, sensitive-argument policy, lazy-load module generation, tool-schema/capability generation, permission policy, allowed-tool scope, hook-set generation, and command completion generation. A command visible to users is not automatically visible to the model, bridge, remote client, keybinding, or sub-agent; each surface needs an explicit allow path, and disabled/hidden/user-only/model-disabled commands must fail closed after every registry refresh. Immediate commands that bypass queueing must be opt-in, side-effect bounded, and revalidate the finalized input snapshot, pasted-content expansion, prompt stash/restore state, loading state, command generation, and current policy before execution. Prompt-backed skills that inject model-visible content, hidden meta messages, scoped tools, hooks, forked agents, or model/effort overrides must label their source and generation, preserve lower-precedence untrusted content, and reauthorize before granting scoped tool rules or registering hooks. Command completion callbacks that append transcript entries, hidden model-visible messages, next input, or automatic query submission must bind to the original command invocation identity, args digest, session/incarnation, command generation, and current privacy/policy state; stale, duplicate, late, or post-abort completions must be ignored or surfaced as uncertainty. Sensitive command args, command bodies, plugin/source names, local paths, raw prompts, hidden meta-message bodies outside their intended model-visible channel, and free-form command errors must be redacted from user-visible transcript renderings, telemetry, logs, search indexes, and diagnostics unless explicit product policy requires a visible record.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-lifecycle-hooks.md

@@ -0,0 +1,92 @@
+# Agent lifecycle hooks framework
+
+Reusable mechanics for a **user-extensible hook surface**: how an agent runtime lets operators inject external logic (a command, a script, an in-process callback) at fixed points in the turn/tool lifecycle to observe, gate, modify, or block agent behavior — without forking the runtime.
+
+Use this when building or reviewing a hook/extension system for an agent. It sits beside:
+- `agent-turn-lifecycle.md` — owns *where* in the loop each hook fires (session start, pre/post tool, pre/post compact, stop).
+- `agent-command-sandbox.md` — owns the approval/sandbox engine that a permission hook can short-circuit.
+- `agent-tool-dispatch.md` — owns the tool router whose pre/post points the tool hooks wrap.
+
+## The event surface
+
+Define a closed, named set of lifecycle events. A representative, well-covered set:
+
+| Event | Fires | Can gate? | Typical scope |
+|---|---|---|---|
+| SessionStart | session/thread begins | no (observe + inject context) | thread |
+| UserPromptSubmit | user input accepted, before sampling | yes (block/inject) | turn |
+| PreToolUse | before a tool executes | **yes** (allow/deny/ask) | turn |
+| PermissionRequest | when a tool needs approval | **yes** (allow/deny) | turn |
+| PostToolUse | after a tool returns | no (observe + inject) | turn |
+| PreCompact | before context compaction | yes (influence/abort) | turn |
+| PostCompact | after compaction | no (observe) | turn |
+| SubagentStart | a sub-agent/child turn begins | no (observe + inject) | thread |
+| SubagentStop | a sub-agent finishes | **yes** (block to continue) | turn |
+| Stop | turn is about to complete | **yes** (block to continue) | turn |
+
+Two design rules from this table:
+- **Not every event takes a matcher.** Tool-scoped events (pre/post tool, permission, compact, subagent) match against a target (tool name, compaction trigger, source); prompt-submit and stop fire unconditionally. Encode which events have meaningful matchers so config that puts a matcher on a non-matching event is ignored predictably rather than silently mis-dispatched.
+- **Scope matters for state keying.** Session/subagent-start hooks are thread-scoped (they set up state for the whole thread); the rest are turn-scoped. Key any persisted hook state by event scope so a turn-scoped hook's state doesn't leak across the thread.
+
+## Dispatch semantics
+
+When an event fires, select and run the matching handlers:
+
+1. **Select** handlers whose configured event matches and whose matcher (a regex over the target, e.g. `Write|Edit|apply_patch`) matches the input. Events without matchers select all their handlers.
+2. **Dedupe per handler.** If one handler's matcher has several alias branches that all match the same target, run it **once**, not once per alias. (A `Write|Edit` hook fires a single time for one edit call.)
+3. **Run handlers concurrently but report in deterministic configured order.** Launch selected handlers in parallel for latency, but sort results back into configuration order before applying them — operators expect "first hook wins" to mean *first in config*, not *first to finish*. Track completion order separately if you need it for telemetry. Concurrent execution only orders the *decision aggregation*, not handler **side effects**: two hooks that each mutate external state still race. Require hook handlers to be side-effect-independent (ideally idempotent); provide an explicit **sequential mode** for the rare case where handlers have ordering dependencies, rather than pretending config-order result sorting serializes their effects.
+4. **Aggregate decisions by precedence** (see decision model). With multiple gating hooks on one event, a safe default is: any **Deny** wins over **Ask**, which wins over **Allow**; ties broken by configured order. Make the precedence explicit and documented — "see below" is not a spec; operators must be able to predict the outcome when two hooks disagree.
+
+**Bound hook fan-out.** N matching handlers spawned concurrently, times every tool call in a tight loop, is a subprocess storm (effectively a fork bomb). Cap concurrent hook processes with a pool/semaphore and cap handlers-per-event; queue or reject beyond the cap rather than spawning unboundedly.
+
+### Decision model
+
+A gating hook returns one of: **Allow**, **Deny(reason)**, **Ask** (escalate to user), or **Block** (for Stop: refuse to stop and continue with an injected prompt). Plus, most hooks can return **additional context** to inject into the turn regardless of decision. Normalize synonyms (e.g. `Block`→`Deny` for tool gating) into a single internal enum so call sites branch on one type.
+
+- A **deny must carry a reason** that becomes model-visible — the model needs to know *why* a tool was blocked to adapt, not just that it failed. **Bound repeated identical denied calls per turn**: a deny that the model answers by retrying the exact same call is an infinite loop; after a small repeat count, escalate to a hard turn-level stop rather than re-denying forever (see `agent-turn-lifecycle.md` outer-loop bound).
+- **A permission hook outranks the built-in *interactive* approval flow, but not a non-overridable policy.** If a `PermissionRequest` hook returns a decision, honor it and skip the normal user/guardian prompt; only fall through to the standard approval path when no hook decides. This lets an operator pre-authorize or hard-forbid classes of actions non-interactively. A hook **Allow** must not, however, escalate past a hard/forbidden policy denial — a hook can waive an interactive prompt, not a non-overridable safety rule. Deny always composes (a hook Deny stands even if policy would allow).
+- For `Stop` / `SubagentStop` hooks, a block must supply a continuation prompt; a block with no prompt is a no-op (warn and proceed to stop) — otherwise the turn hangs unable to either stop or continue. Cap consecutive stop-block continuations (see `agent-turn-lifecycle.md` outer-loop bound).
+
+## Running external command hooks safely
+
+The most common handler type shells out to a user command. Treat that command as **untrusted, slow, and failure-prone**:
+
+- **Pass event data as JSON on stdin**, not as argv (avoids quoting/injection and argv length limits). Emit a **stable, versioned wire shape** (snake_case keys, RFC3339 timestamps) — operators script against it, so changing it silently breaks their hooks.
+- **Always time-bound** each command (per-handler timeout) and **kill on drop / kill on timeout** so a hung hook can't wedge the turn. A timed-out hook is a captured error, not a crash.
+- **Capture, never panic.** Spawn failure, stdin-write failure, non-zero exit, timeout, and malformed output are all *results* with an error field — one bad hook must not take down the runtime. Decide per event whether a hook failure is `fail-continue` (run the rest, proceed) or `fail-abort` (stop the operation): gating events lean fail-closed for safety-relevant denials, observation events lean fail-open.
+- **Bound the captured output.** Hook stdout/stderr can be arbitrarily large; spill/truncate to a cap before storing or feeding any of it back into context, or a chatty hook blows up memory and the context window. Truncation must be visible (marked), not silent.
+- **Parse output defensively.** A hook's stdout is parsed into the decision/reason/additional-context structure; malformed JSON is a handled parse error (treated as "no decision"), never a trust-the-bytes path.
+- **Treat hook-injected additional context as untrusted, model-visible data — the prompt-injection vector.** A command hook can echo attacker-controlled bytes (file contents, web responses) as additional context; injected verbatim it becomes a prompt-injection / agent-hijack path. Subject it to the same injection-trust handling as tool output: sanitize/quote it, mark its provenance, and gate how much weight it carries by the hook's trust level. Never inject raw hook stdout straight into the model turn.
+- **Run hooks in a defined working directory and a minimal, explicit environment.** Pass an allowlisted env so behavior is reproducible and a third-party hook can't inherit ambient state — and in particular **do not forward secrets (API keys, tokens) into hook commands by default**; an untrusted hook with the agent's credentials in its env can exfiltrate them.
+- **Kill the hook's whole process group, not just the parent.** A hook that spawns children leaves orphaned grandchildren when only the parent is killed on timeout/drop. Run each hook in its own process group and terminate the group.
+
+## Anti-patterns
+
+- An open-ended/implicit event set (operators can't know what they can hook; runtime can't validate config). Close the set and name it.
+- Dispatching in completion order rather than configured order (nondeterministic "which hook won").
+- Running a matcher-aliased hook once per alias branch (duplicate side effects for one tool call).
+- Letting a hook command run unbounded (no timeout, no kill-on-drop) — one hung hook freezes every turn.
+- Feeding raw, unbounded hook stdout back into context (memory blowup; context poisoning via untrusted hook output).
+- A deny decision with no model-visible reason (model can't adapt; retries the same blocked action).
+- A `Stop`-block with no continuation prompt and no cap (turn can neither stop nor progress).
+- Panicking on hook failure instead of capturing it as a typed result (one operator's broken script crashes the agent).
+- Changing the hook payload wire shape without versioning (silently breaks every operator's scripts).
+- Treating a permission-hook decision as advisory while still prompting the user (defeats non-interactive pre-authorization; double-gates) — or the reverse, letting a hook Allow override a hard/non-overridable policy denial.
+- Spawning all matching handlers with no concurrency cap (subprocess storm under a tight tool loop). Pool/semaphore the fan-out.
+- Forwarding the agent's full environment (including secrets) into untrusted hook commands. Pass a minimal allowlist.
+- Killing only the hook's parent process on timeout (orphaned grandchildren). Kill the process group.
+- Injecting raw hook stdout as model-visible context (prompt-injection vector). Sanitize and gate by trust.
+- Assuming config-order result sorting serializes side-effecting hooks (it doesn't — only decisions are ordered). Require independent/idempotent handlers or a sequential mode.
+- Leaving a deny→model-retries-identical-call loop unbounded. Cap repeated identical denied calls per turn.
+
+## Hook and classifier outputs as untrusted
+
+Hook, prompt-hook, agent-hook, and automatic-classifier outputs are untrusted control-plane inputs, not authority. Validate result discriminants and schema, bind each response to the pending request and abort signal, time-bound execution, reject late results after cancellation or generation/policy/input changes, and let explicit deny/ask rules override hook or classifier allow results. A hook may narrow, ask, deny, add context, or provide a reviewed input transform; it must not silently widen permission scope, persist a broad allow rule, inject executable instructions, leak environment secrets into headers/prompts/logs, or override system, developer, current-user, managed-policy, or explicit-deny constraints.
+
+## Post-turn hooks and follow-on background work
+
+Treat post-turn hooks and follow-on background work as a continuation-finality boundary. Capture the turn context once, bind hook execution to principal/session/workspace, entrypoint mode, query source, agent identity, permission mode, hook-set generation, abort signal, transcript/message snapshot, and capability/policy generation, and restrict cache-safe context snapshots or background bookkeeping to entrypoints allowed to own that state. Background suggestions, memory extraction, classification, cleanup, or other post-turn jobs must be mode-gated, excluded from subagent or noninteractive timelines unless explicitly supported, isolated from the main transcript unless they produce an authorized message, and fenced so late results after abort, new input, root/workspace switch, or session/agent drift cannot mutate state. Stop, task-completed, idle, or similar continuation hooks need deterministic ordering, per-hook progress/effect identity, bounded output aggregation, explicit blocker versus nonblocking-error finality, and a model-visible blocker only when continuation is actually prevented. If a hook prevents continuation, aborts, or is canceled, return a durable continuation state rather than relying on UI notification; if hook orchestration itself fails, surface a degraded warning without inventing a blocker. Summaries, notifications, and diagnostics may expose bounded counts, categories, durations, and sanitized reason codes, but not raw hook commands, prompts, task or team names, outputs, local paths, credentials, telemetry ids, or free-form errors.
+
+## Runtime hook configuration control plane
+
+Treat runtime hook configuration as a mutable control plane, not a passive preference file. Build the effective hook set from declared source precedence and trust policy, with managed or policy-locked sources able to restrict lower-trust sources but never the reverse. Capture an immutable hook-set generation for each model turn, tool invocation, background task, watcher, and session-scoped callback registration; when configuration changes, reset stale settings caches, recompute the effective set from one authoritative source snapshot, validate it, and publish the new generation only through serialization or compare-and-swap. Failed or partial refresh keeps the prior valid generation, and the runtime must not report hook changes as applied until atomic publication succeeds. Either keep the old generation isolated for already-running work or force an explicit reload/restart/generation change before new hooks can affect model-visible context, permission decisions, environment mutation, filesystem watching, or tool output mutation. Late hook results, callback successes, dynamic watch paths, environment edits, permission updates, and additional context from an old generation must be discarded or re-authorized after hook-set, policy, workspace, principal, session, capability, or sandbox drift. Session-only function callbacks and hook-injected tools need bounded execution, cleanup on removal/abort/shutdown, no persistence unless explicitly declared safe, and no authority to outlive the session that registered them. Network or model-backed hooks are external control inputs: enforce allowlists, proxy/sandbox policy, SSRF and header-injection defenses, timeout/abort cleanup, output schema validation, no recursive hook triggering, and redaction before prompts, transcripts, logs, telemetry, or user-visible summaries. Outbound hook payloads need an explicit allowlisted schema, default-deny sensitive fields, size bounds, environment/header allowlist intersection, and no raw prompts, tool bodies, file contents, local paths, credentials, URLs, headers, or diagnostic strings unless that exact field class is authorized for that hook purpose. Hook-driven file watching and working-directory callbacks must validate watch paths against the current authorized workspace/root set, clear stale environment artifacts on directory change, close old watchers before replacing them, and treat watcher or cleanup failure as degraded control-plane state rather than proof that a hook was applied.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-messaging.md

@@ -0,0 +1,5 @@
+# Agent-To-Agent Messaging
+
+## Agent-to-agent mailbox and peer messaging
+
+Treat agent-to-agent mailbox, inbox polling, peer messaging, and cross-session prompt delivery as model-visible communication and control planes, not ordinary chat. Inbound messages must enter context only as untrusted, labeled, bounded data with sender, recipient, team/session/workspace, transport scheme, message id or stable dedupe key, request id when present, timestamp, delivery generation, and whether the message is plain text or structured control. Plain text and structured control messages need distinct schemas and routes; structured permission, approval, plan, mode, sandbox, task, team-permission, or shutdown messages must not be broadcast or sent across peer/session boundaries unless the protocol explicitly supports that control type and authority tuple. Permission, approval, plan, mode, sandbox, and shutdown replies must bind to a pending request id, sender role or control-channel authority, target agent, task/session/incarnation, policy/capability/permission generation, original control tuple, and normalized payload digest; reject forged, late, duplicate, stale, unknown, role-invalid, or post-terminal replies. Mark messages read only after successful delivery into model context or durable in-process queueing; clear queued messages only after successful submit, and treat mailbox read/write/lock/mark-read failures as visible delivery uncertainty rather than empty-success or sent-success. Duplicate polls must dedupe by stable request/tool/message ids, busy messages must drain only at safe turn or tool boundaries, and terminal tasks/sessions must reject late injected messages. Cross-machine or cross-session prompt delivery requires explicit user consent that automatic classifiers, bypass modes, or cached approvals cannot satisfy; revalidate the peer handle, connection state, recipient identity, and transport generation immediately before send because consent may take time. Broadcast/fanout needs explicit recipient enumeration, self-exclusion, bounded fanout, and per-recipient delivery or failure accounting. Message wrappers must escape or bound sender-supplied attributes and bodies, preserve prompt-injection labeling, and never leak raw message bodies, control payloads, socket paths, session handles, local transport addresses, prompts, credentials, or sensitive paths into diagnostics; route sink policy to `platform-observability`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-runtime-bootstrap.md

@@ -0,0 +1,5 @@
+# Agent Runtime Startup And Configuration Bootstrap
+
+## Runtime startup and configuration bootstrap
+
+Treat runtime startup and configuration bootstrap as a trust-boundary state machine, not ordinary config loading. Bind startup effects to principal/session/workspace, entrypoint mode, trust state, settings source class and generation, host-managed runtime-variable ownership, managed-policy generation, network-transport generation, cwd/project-root/worktree generation, hook snapshot generation, cleanup generation, and telemetry initialization generation. Before workspace/project trust, trusted global/user/flag/policy sources may apply according to policy, while project-local or workspace-derived settings may apply only when explicitly allowlisted as safe and unable to widen authority, redirect traffic, load code, change provider/model/routing, modify proxy/TLS material, alter hooks/tools/sandbox/telemetry behavior, affect model-visible context, or expose credentials; all other project-local or workspace-derived configuration must wait for trust and fresh authorization. Host-owned spawn variables and provider-routing variables must not be overridden by lower-trust settings when the host declares ownership. API-only tunnel or routing variables must stay scoped to the intended API client and must not leak into unrelated connector, HTTP, streaming, shell, hook, or tool transports. Early certificate, proxy, and mutual-auth setup must use only trusted sources, preserve base trust roots when adding custom trust material, respect bypass rules, and clear/rebuild cached agents or clients after post-trust environment changes. Cwd, project-root, or worktree switches must invalidate file, memory, prompt, hook, tool, permission, and source-control caches and refresh hook/config snapshots before commands, tools, hooks, skills, background jobs, or model-visible context load from the new root. Startup background jobs, prefetches, remote settings fetches, memory tasks, release notes, and telemetry must be gated by entrypoint mode and trust state, idempotent across retries, cancelable during shutdown, and unable to race noninteractive install/sync paths. Unsafe bypass modes need explicit environment checks and a fail-closed degraded state. Diagnostics may expose bounded categories, generations, mode labels, and sanitized reason codes, but not raw local paths, environment variable names or values, provider names, endpoint details, credentials, command lines, project structure, config bodies, or free-form setup errors.