@sayknow-cli/coding-agent 0.2.6 → 0.3.0

package/src/defaults/skc/skills/ultragoal/SKILL.md

@@ -107,6 +107,21 @@ Loop until `skc ultragoal status` reports all goals complete:
    `skc ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy SKC goal blocks goal create in this thread>" --skc-goal-json <goal-get-json-or-path>`
 11. Resume failed goals with `skc ultragoal complete-goals --retry-failed`.
 
+## Blocker triage and pause discipline
+
+An active Ultragoal run must not give up on a blocker by pausing the goal and asking the user. Classify every blocker before deciding what to do, and default to `resolvable` when unsure:
+
+- **`resolvable`** — anything the agent can act on: failing tests, missing implementation, a dependency to install, an ambiguous-but-inferable detail, investigation. **Never pause.** Exhaust autonomous resolution first: investigate, `skc ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "..." --evidence "..." --rationale "..."`, delegate an `executor`, or preserve the blocker durably with `skc ultragoal checkpoint --status blocked` / `skc ultragoal record-review-blockers` and keep scheduling the next goal.
+- **`human_blocked`** — only the user can act: credentials/secrets, a manual or physical step, an external approval/decision, access the agent lacks. Pause is the last resort and is gated.
+
+`goal({"op":"pause"})` is **blocked at runtime** while an Ultragoal run is active unless the latest durable ledger event classifies the current blocker as `human_blocked`. To pause, record the classification immediately before pausing and cite the human-only dependency as evidence:
+
+```sh
+skc ultragoal classify-blocker --classification human_blocked --evidence "<the specific human-only dependency>" [--goal-id <id>]
+```
+
+Recording `--classification resolvable` is an audit note only; it never authorizes a pause. The `ask` tool stays blocked during active runs regardless of classification — record unresolved decisions as durable blockers instead of prompting.
+
 ## Dynamic steering
 
 Use `skc ultragoal steer` when real findings or blockers prove the current story decomposition should change while the aggregate objective and constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.
@@ -199,6 +214,7 @@ An ultragoal story cannot be checkpointed `complete` until the active agent has
    - CLI surfaces require runtime argv replay: `replaySafe: true`, an allowlisted argv `command`, and replayed normalized stdout matching `recordedStdout`; unsafe commands require audited `replayExempt` metadata with exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs` plus a structurally valid fallback artifact. Allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
    - Native/desktop/tui surfaces require a structurally valid screenshot, PTY capture with terminal control codes, or app-automation transcript.
    - API/package/algorithm/math surfaces require a real artifact file or typed receipt. Bare `inlineEvidence` text alone is not sufficient for any surface.
+   - The mandatory **computer-use** red-team suite (`kill-switch-bypass`, `suspended-enforcement`, `permission-revoked`, …) is conditional, not universal: require it only when computer/desktop control is genuinely part of the product surface being dogfooded. For every other product type, prove the change through the matching live surface instead — browser-use automation for web/GUI, bash/CLI live invocation or argv replay for CLI, and real artifacts or typed receipts for API/package/algorithm/math. Editing docs, prompts, or skills that merely mention computer-use does not by itself make the computer-use suite applicable; pick the red-team surface that matches what the change actually ships.
 7. The executor QA/red-team lane must report a matrix using `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`. Not-applicable rows are allowed only in `contractCoverage` and `surfaceEvidence`; each `status: "not_applicable"` row requires `contractRef` plus `reason`. `adversarialCases` rows cannot be not-applicable.
 8. Run a final code review pass and fold it into the strict quality gate. Clean means `architectReview.architectureStatus`, `architectReview.productStatus`, and `architectReview.codeStatus` are all `"CLEAR"`, `architectReview.recommendation` is `"APPROVE"`, executor QA statuses are `"passed"`, iteration is `"passed"` with `fullRerun: true`, every evidence field is non-empty, every required matrix row is present, and every blockers array is empty. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing evidence, missing or shallow matrix rows, plan/code mismatches, or non-empty blockers are non-clean.
 9. If any lane finds an issue, do **not** checkpoint `complete` and do **not** call `goal({"op":"complete"})`. Record durable blocker work instead:

package/src/defaults/skc-defaults.ts

@@ -10,10 +10,11 @@ import ralplanSkill from "./skc/skills/ralplan/SKILL.md" with { type: "text" };
 import teamSkill from "./skc/skills/team/SKILL.md" with { type: "text" };
 import aiSlopCleanerFragment from "./skc/skills/ultragoal/ai-slop-cleaner.md" with { type: "text" };
 import ultragoalSkill from "./skc/skills/ultragoal/SKILL.md" with { type: "text" };
+import ponytailRule from "./skc/rules/ponytail.md" with { type: "text" };
 
 export const DEFAULT_SKC_DEFINITION_NAMES = ["deep-interview", "ralplan", "team", "ultragoal"] as const;
 export type DefaultSkcDefinitionName = (typeof DEFAULT_SKC_DEFINITION_NAMES)[number];
-export type DefaultSkcDefinitionKind = "skill" | "skill-fragment";
+export type DefaultSkcDefinitionKind = "skill" | "skill-fragment" | "rule";
 export type EmbeddedDefaultSkcSkill = {
 	name: DefaultSkcDefinitionName;
 	description: string;
@@ -39,7 +40,17 @@ export interface DefaultSkcSkillFragmentDefinition {
 	content: string;
 }
 
-export type DefaultSkcDefinition = DefaultSkcSkillDefinition | DefaultSkcSkillFragmentDefinition;
+export interface DefaultSkcRuleDefinition {
+	kind: "rule";
+	name: string;
+	relativePath: string;
+	content: string;
+}
+
+export type DefaultSkcDefinition =
+	| DefaultSkcSkillDefinition
+	| DefaultSkcSkillFragmentDefinition
+	| DefaultSkcRuleDefinition;
 
 export interface InstallDefaultSkcDefinitionsOptions {
 	check?: boolean;
@@ -59,6 +70,12 @@ export type DefaultSkcDefinitionInstallFile =
 			parentSkillName: DefaultSkcDefinitionName;
 			path: string;
 			status: DefaultSkcInstallStatus;
+	  }
+	| {
+			kind: "rule";
+			name: string;
+			path: string;
+			status: DefaultSkcInstallStatus;
 	  };
 
 export interface DefaultSkcDefinitionInstallResult {
@@ -106,6 +123,7 @@ const DEFAULT_SKC_DEFINITIONS: readonly DefaultSkcDefinition[] = [
 		relativePath: "skill-fragments/ultragoal/ai-slop-cleaner.md",
 		content: aiSlopCleanerFragment,
 	},
+	{ kind: "rule", name: "ponytail", relativePath: "rules/ponytail.md", content: ponytailRule },
 ];
 
 export function getDefaultSkcDefinitions(): readonly DefaultSkcDefinition[] {
@@ -174,6 +192,13 @@ export async function installDefaultSkcDefinitions(
 				path: destination,
 				status,
 			});
+		} else if (definition.kind === "rule") {
+			files.push({
+				kind: definition.kind,
+				name: definition.name,
+				path: destination,
+				status,
+			});
 		} else {
 			files.push({
 				kind: definition.kind,

package/src/edit/modes/replace.ts

@@ -42,7 +42,7 @@ let scoreSequenceFuzzyNative:
 let findBestFuzzyMatchNative:
 	| ((content: string, target: string, threshold: number) => NativeBestFuzzyMatchResult)
 	| undefined;
-void import("../../../../natives/native/index.js")
+void import("@sayknow-cli/natives")
 	.then(mod => {
 		if (typeof mod.h02ScoreSequenceFuzzy === "function") {
 			scoreSequenceFuzzyNative = mod.h02ScoreSequenceFuzzy;

package/src/extensibility/extensions/runner.ts

@@ -6,6 +6,7 @@ import type { CredentialDisabledEvent, ImageContent, Model, ProviderResponseMeta
 import type { KeyId } from "@sayknow-cli/tui";
 import { logger } from "@sayknow-cli/utils";
 import type { ModelRegistry } from "../../config/model-registry";
+import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/unattended-session";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { SessionManager } from "../../session/session-manager";
 import type {
@@ -180,6 +181,7 @@ export class ExtensionRunner {
 	#getContextUsageFn: () => ContextUsage | undefined = () => undefined;
 	#compactFn: (instructionsOrOptions?: string | CompactOptions) => Promise<void> = async () => {};
 	#getSystemPromptFn: () => string[] = () => [];
+	#getWorkflowGateFn: () => WorkflowGateEmitter | undefined = () => undefined;
 	#newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
 	#branchHandler: BranchHandler = async () => ({ cancelled: false });
 	#navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
@@ -234,6 +236,7 @@ export class ExtensionRunner {
 		this.#hasPendingMessagesFn = contextActions.hasPendingMessages;
 		this.#shutdownHandler = contextActions.shutdown;
 		this.#getSystemPromptFn = contextActions.getSystemPrompt;
+		this.#getWorkflowGateFn = contextActions.getWorkflowGate ?? (() => undefined);
 
 		// Command context actions (optional, only for interactive mode)
 		if (commandContextActions) {
@@ -463,6 +466,7 @@ export class ExtensionRunner {
 			shutdown: () => this.#shutdownHandler(),
 			getSystemPrompt: () => this.#getSystemPromptFn(),
 			hasQueuedMessages: () => this.#hasPendingMessagesFn(), // deprecated alias
+			workflowGate: this.#getWorkflowGateFn(),
 		};
 	}
 

package/src/extensibility/extensions/types.ts

@@ -32,6 +32,7 @@ import type { PythonResult } from "../../eval/py/executor";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { CustomEditor } from "../../modes/components/custom-editor";
+import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/unattended-session";
 import type { Theme } from "../../modes/theme/theme";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
@@ -310,6 +311,11 @@ export interface ExtensionContext {
 	getSystemPrompt(): string[];
 	/** @deprecated Use hasPendingMessages() instead */
 	hasQueuedMessages(): boolean;
+	/**
+	 * Unattended workflow-gate bridge. Present only when the session runs in
+	 * unattended/RPC mode; `undefined` in interactive/TUI mode (notify-only).
+	 */
+	workflowGate?: WorkflowGateEmitter;
 }
 
 /**
@@ -1234,6 +1240,8 @@ export interface ExtensionContextActions {
 	getContextUsage: () => ContextUsage | undefined;
 	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
 	getSystemPrompt: () => string[];
+	/** Unattended workflow-gate bridge (present only in unattended/RPC mode). */
+	getWorkflowGate?: () => WorkflowGateEmitter | undefined;
 }
 
 /** Actions for ExtensionCommandContext (ctx.* in command handlers). */

package/src/extensibility/plugins/index.ts

@@ -6,4 +6,5 @@ export * from "./loader";
 export * from "./manager";
 export * from "./marketplace";
 export * from "./parser";
+export * from "./security-scanner";
 export type * from "./types";

package/src/extensibility/plugins/manager.ts

@@ -10,7 +10,9 @@ import {
 	isEnoent,
 	logger,
 } from "@sayknow-cli/utils";
+import { settings } from "../../config/settings";
 import { extractPackageName, parsePluginSpec } from "./parser";
+import { scanPluginDir, toDoctorChecks } from "./security-scanner";
 import type {
 	DoctorCheck,
 	DoctorOptions,
@@ -211,6 +213,9 @@ export class PluginManager {
 		}
 		// null = use defaults
 
+		// Security scan — advisory hook, runs after package is on disk but before config is saved.
+		await this.#runSecurityScan(pkg.name, path.join(getPluginsNodeModules(), actualName));
+
 		// Update runtime config
 		const config = await this.#ensureConfigLoaded();
 		config.plugins[pkg.name] = {
@@ -614,6 +619,14 @@ export class PluginManager {
 					}
 				}
 			}
+
+			// Security scan for installed plugin
+			try {
+				const secReport = await scanPluginDir(pluginPath);
+				checks.push(...toDoctorChecks(name, secReport));
+			} catch {
+				// advisory — never fail doctor
+			}
 		}
 
 		// Check for orphaned runtime config entries
@@ -632,6 +645,43 @@ export class PluginManager {
 		return checks;
 	}
 
+	async #runSecurityScan(pluginName: string, dir: string): Promise<void> {
+		// Resolve the scan mode defensively — this can run from CLI paths where Settings
+		// is not initialized, and an advisory scan must NEVER abort an install.
+		let mode = "warn";
+		try {
+			mode = settings.get("plugins.security.scanMode");
+		} catch {
+			mode = "warn";
+		}
+		if (mode === "off") return;
+		try {
+			const report = await scanPluginDir(dir);
+			if (report.riskLevel === "none") return;
+			logger.warn("Plugin security scan flagged risky patterns", {
+				plugin: pluginName,
+				riskLevel: report.riskLevel,
+				score: report.score,
+				findings: report.findings,
+			});
+			// score: 100 = safe, lower = riskier — block when it drops to/under the threshold.
+			let threshold = 60;
+			try {
+				threshold = settings.get("plugins.security.riskThreshold");
+			} catch {
+				threshold = 60;
+			}
+			if (mode === "block" && report.score <= threshold) {
+				throw new Error(
+					`Plugin "${pluginName}" blocked by security policy: ${report.riskLevel} risk (score ${report.score}). Set plugins.security.scanMode=warn to override.`,
+				);
+			}
+		} catch (err) {
+			if (mode === "block") throw err;
+			logger.debug("Security scan skipped due to error", { plugin: pluginName, error: err });
+		}
+	}
+
 	async #fixMissingPlugin(): Promise<boolean> {
 		try {
 			const proc = Bun.spawn(["bun", "install"], {

package/src/extensibility/plugins/marketplace/manager.ts

@@ -11,6 +11,8 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 import { isEnoent, logger, pathIsWithin } from "@sayknow-cli/utils";
+import { settings } from "../../../config/settings";
+import { scanPluginDir } from "../security-scanner";
 
 import { cachePlugin } from "./cache";
 import { classifySource, fetchMarketplace, parseMarketplaceCatalog, promoteCloneToCache } from "./fetcher";
@@ -298,6 +300,9 @@ export class MarketplaceManager {
 			}
 		}
 
+		// Security scan — advisory hook, runs after plugin is on disk but before registry write.
+		await this.#runSecurityScan(pluginId, cachePath);
+
 		// Only now clean up old entries — new cache succeeded, so it is safe to remove old ones.
 		if (existing && existing.length > 0) {
 			// Remove from scope-appropriate registry first, then cross-check refs before disk deletion.
@@ -745,6 +750,43 @@ export class MarketplaceManager {
 		}
 	}
 
+	async #runSecurityScan(pluginName: string, dir: string): Promise<void> {
+		// Resolve the scan mode defensively — this can run from CLI paths where Settings
+		// is not initialized, and an advisory scan must NEVER abort an install.
+		let mode = "warn";
+		try {
+			mode = settings.get("plugins.security.scanMode");
+		} catch {
+			mode = "warn";
+		}
+		if (mode === "off") return;
+		try {
+			const report = await scanPluginDir(dir);
+			if (report.riskLevel === "none") return;
+			logger.warn("Plugin security scan flagged risky patterns", {
+				plugin: pluginName,
+				riskLevel: report.riskLevel,
+				score: report.score,
+				findings: report.findings,
+			});
+			// score: 100 = safe, lower = riskier — block when it drops to/under the threshold.
+			let threshold = 60;
+			try {
+				threshold = settings.get("plugins.security.riskThreshold");
+			} catch {
+				threshold = 60;
+			}
+			if (mode === "block" && report.score <= threshold) {
+				throw new Error(
+					`Plugin "${pluginName}" blocked by security policy: ${report.riskLevel} risk (score ${report.score}). Set plugins.security.scanMode=warn to override.`,
+				);
+			}
+		} catch (err) {
+			if (mode === "block") throw err;
+			logger.debug("Security scan skipped due to error", { plugin: pluginName, error: err });
+		}
+	}
+
 	/**
 	 * Compute the marketplace root directory for source resolution.
 	 *