@namzu/sdk 44.3.0 → 45.1.0

package/src/types/authorization/index.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { MAX_CUSTOM_PATTERN_LENGTH } from '../../constants/authorization/index.js'
+import type { ShellDialect, ToolDefinition } from '../tool/index.js'
 
 export type GateDecision = 'allow' | 'deny' | 'review'
 
@@ -81,9 +82,56 @@ export type AuthorizationRule =
 			/** The argument key, at the top level of the tool's input. */
 			argument: string
 			pattern: string
-			decision: 'allow' | 'deny'
+			/**
+			 * `review` sends a matching call to the review policy — a person,
+			 * or the turn's mode — instead of deciding it here. It matches as
+			 * `deny` does (any segment of a command line), because it is a
+			 * restriction: a rule that asks before `git push` must also ask
+			 * before `true; git push`.
+			 */
+			decision: 'allow' | 'deny' | 'review'
 	  }
 	| { type: 'allow_by_tier'; tiers: string[] }
+	| {
+			/**
+			 * A decision the host computes in code, in its place in the list.
+			 *
+			 * A pattern is the wrong tool for a rule about what a command line
+			 * DOES: a regular expression over its text has to re-implement the
+			 * shell's quoting, and every form it misses (`$'…'`, a line
+			 * continuation, a quoted separator) is a way past the rule. A host
+			 * that needs such a rule reads the line with `lexShellCommandLine`
+			 * and decides on the words bash will pass, here.
+			 *
+			 * `decide` returns a decision, or `null` to let the next rule
+			 * decide. A `decide` that throws is read as `deny`: a rule that
+			 * could not reach a verdict must not let the call through.
+			 */
+			type: 'predicate'
+			/**
+			 * What the rule refuses or allows, in words. It is the reason the
+			 * gate reports when this rule decides, so it should tell a model
+			 * whether a different input could fare better.
+			 */
+			description: string
+			decide: AuthorizationPredicate
+	  }
+
+/** The call an `AuthorizationRule` of type `predicate` is asked about. */
+export interface AuthorizationPredicateCall {
+	readonly toolName: string
+	readonly toolInput: unknown
+	readonly toolDef: ToolDefinition | undefined
+	/**
+	 * The shell a command line in this call runs in: the caller's
+	 * (`ToolCallContext.commandDialect`), or `sh` when it did not say, which
+	 * is the reading that holds whichever shell runs it.
+	 */
+	readonly commandDialect: ShellDialect
+}
+
+/** The code behind an `AuthorizationRule` of type `predicate`. */
+export type AuthorizationPredicate = (call: AuthorizationPredicateCall) => GateDecision | null
 
 const AllowReadOnlySchema = z.object({
 	type: z.literal('allow_read_only'),
@@ -121,12 +169,21 @@ const ArgumentPatternSchema = z.object({
 	// fail-open shape this rule type exists to remove.
 	argument: z.string().min(1),
 	pattern: z.string().max(MAX_CUSTOM_PATTERN_LENGTH),
-	decision: z.enum(['allow', 'deny']),
+	decision: z.enum(['allow', 'deny', 'review']),
 })
 const AllowByTierSchema = z.object({
 	type: z.literal('allow_by_tier'),
 	tiers: z.array(z.string()),
 })
+const PredicateSchema = z.object({
+	type: z.literal('predicate'),
+	// A rule that says nothing about itself produces a refusal nobody can
+	// reason about.
+	description: z.string().min(1),
+	decide: z.custom<AuthorizationPredicate>((value) => typeof value === 'function', {
+		message: 'decide must be a function',
+	}),
+})
 
 export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	AllowReadOnlySchema,
@@ -137,6 +194,7 @@ export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	CustomPatternSchema,
 	ArgumentPatternSchema,
 	AllowByTierSchema,
+	PredicateSchema,
 ])
 
 export const AuthorizationGateConfigSchema = z.object({

package/src/types/browser/index.ts

@@ -0,0 +1,341 @@
+// ---------------------------------------------------------------------------
+// The browser contract: what a browser host does for the `browser` and
+// `browser_act` tools. The SDK owns the model-facing tools and this
+// interface; a host package (for example `@namzu/browser`) owns the engine.
+// ---------------------------------------------------------------------------
+
+/** Every action the `browser` tool (observe and navigate) can ask for. */
+export type BrowserObserveActionName =
+	| 'navigate'
+	| 'back'
+	| 'forward'
+	| 'reload'
+	| 'snapshot'
+	| 'screenshot'
+	| 'scroll'
+	| 'wait_for'
+	| 'tabs'
+
+/** Every action the `browser_act` tool (change the page) can ask for. */
+export type BrowserActActionName =
+	| 'click'
+	| 'type'
+	| 'fill_form'
+	| 'select'
+	| 'press'
+	| 'hover'
+	| 'upload'
+	| 'dialog'
+
+export type BrowserActionName = BrowserObserveActionName | BrowserActActionName
+
+export type BrowserScrollDirection = 'up' | 'down' | 'left' | 'right'
+
+export type BrowserTabsOp = 'list' | 'select' | 'close' | 'new'
+
+// ---------------------------------------------------------------------------
+// Capabilities — frozen at host construction; the model reads them through
+// the tools' descriptions and schemas.
+// ---------------------------------------------------------------------------
+
+export interface BrowserCapabilities {
+	/** Which engine drives the browser, in words: `local-chromium`, `windows-cdp`. */
+	readonly engine: string
+	/** The browser window is not shown. */
+	readonly headless: boolean
+	/** `screenshot` can return an image. */
+	readonly screenshot: boolean
+	/** `upload` can attach a local file to a file input. */
+	readonly upload: boolean
+	/**
+	 * Exact action subset when known. Absent: every action whose broad flag
+	 * above allows it. Actions outside the subset are removed from the model
+	 * schema and refused before the host is called.
+	 */
+	readonly supportedActions?: readonly BrowserActionName[]
+	/**
+	 * The most snapshot text one call returns. The tool cuts anything longer.
+	 * Absent: {@link BROWSER_SNAPSHOT_MAX_CHARS}.
+	 */
+	readonly snapshotMaxChars?: number
+	/**
+	 * Why the browser cannot be used at all — the engine is not installed,
+	 * the profile is missing. Present, both tools stay mounted, say this in
+	 * their descriptions and refuse every call with it, so the model reads
+	 * the reason once and tells the user instead of retrying.
+	 */
+	readonly unavailableReason?: string
+}
+
+/** Default and ceiling of snapshot text per call, in characters. */
+export const BROWSER_SNAPSHOT_MAX_CHARS = 20_000
+
+/** Longest `wait_for` the tool accepts, in milliseconds. */
+export const BROWSER_WAIT_MAX_MS = 30_000
+
+/** Most fields one `fill_form` call may set. */
+export const BROWSER_FILL_FORM_MAX_FIELDS = 20
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+/**
+ * What the `browser` tool asks of the host. Every URL here has already been
+ * canonicalised by the tool (see `canonicalizeBrowserUrl`): only http, https
+ * or `about:blank`, no credentials, never a cloud metadata address.
+ */
+export type BrowserObserveAction =
+	| { readonly action: 'navigate'; readonly url: string }
+	| { readonly action: 'back' }
+	| { readonly action: 'forward' }
+	| { readonly action: 'reload' }
+	| { readonly action: 'snapshot'; readonly ref?: string; readonly cursor?: string }
+	| { readonly action: 'screenshot'; readonly ref?: string; readonly fullPage?: boolean }
+	| {
+			readonly action: 'scroll'
+			readonly direction: BrowserScrollDirection
+			readonly ref?: string
+			/** Screens to scroll; the host's default when absent. */
+			readonly amount?: number
+	  }
+	| {
+			readonly action: 'wait_for'
+			readonly text?: string
+			readonly textGone?: string
+			readonly timeMs?: number
+	  }
+	| {
+			readonly action: 'tabs'
+			readonly op: BrowserTabsOp
+			/** `select` and `close`: the tab id from `list` or a page header. */
+			readonly tab?: string
+			/** `new`: the address to open; `about:blank` when absent. */
+			readonly url?: string
+	  }
+
+export interface BrowserFormField {
+	readonly ref: string
+	/** Text for a text box; `true`/`false` for a checkbox; the option's label for a select. */
+	readonly value: string
+}
+
+/** The change a `browser_act` call makes. */
+export type BrowserActOperation =
+	| { readonly action: 'click'; readonly ref: string; readonly doubleClick?: boolean }
+	| {
+			readonly action: 'type'
+			readonly ref: string
+			readonly text: string
+			/** Press Enter after typing. */
+			readonly submit?: boolean
+	  }
+	| { readonly action: 'fill_form'; readonly fields: readonly BrowserFormField[] }
+	| { readonly action: 'select'; readonly ref: string; readonly values: readonly string[] }
+	| { readonly action: 'press'; readonly key: string; readonly ref?: string }
+	| { readonly action: 'hover'; readonly ref: string }
+	| { readonly action: 'upload'; readonly ref: string; readonly path: string }
+	| { readonly action: 'dialog'; readonly accept: boolean; readonly promptText?: string }
+
+/**
+ * What the `browser_act` tool asks of the host.
+ *
+ * `origin` is the page origin the model read from the snapshot header
+ * (`Page: <origin> — …`), canonicalised by the tool. **The host MUST compare
+ * it with the live origin of the page it is about to act on, immediately
+ * before acting, and throw a {@link BrowserOriginMismatch} without acting
+ * when they differ.** That comparison is what binds an approval of "click
+ * Place order on shop.example.com" to shop.example.com: a redirect between
+ * the snapshot and the click must not carry the click to another site.
+ */
+export type BrowserActAction = BrowserActOperation & {
+	readonly origin: string
+	/** Return a snapshot of the page after the action. */
+	readonly snapshot?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+
+/** The page an action left the browser on, as the host observed it. */
+export interface BrowserPageInfo {
+	/** Canonical origin (`https://github.com`), or `null` for `about:blank`. */
+	readonly origin: string
+	readonly url: string
+	/** The document title. Page-controlled: the tool quotes and cuts it. */
+	readonly title: string
+	/** The tab's id, e.g. `t1`. */
+	readonly tab: string
+}
+
+export interface BrowserTabInfo extends BrowserPageInfo {
+	readonly active: boolean
+}
+
+export interface BrowserSnapshot {
+	readonly page: BrowserPageInfo
+	/**
+	 * The accessibility tree as text, one element per line, each actionable
+	 * element carrying `[ref=eN]`. Page-controlled: the tool wraps it as
+	 * untrusted content.
+	 */
+	readonly text: string
+	/** Present when more text follows; pass it back as `cursor`. */
+	readonly nextCursor?: string
+}
+
+export interface BrowserScreenshot {
+	readonly page: BrowserPageInfo
+	readonly data: Uint8Array
+	readonly mimeType: 'image/png' | 'image/jpeg'
+	readonly width: number
+	readonly height: number
+}
+
+/**
+ * What an action produced. Every field is optional because actions differ;
+ * the tool renders whichever are present.
+ */
+export interface BrowserResult {
+	/** The page after the action. */
+	readonly page?: BrowserPageInfo
+	/**
+	 * The host's own note, in the host's words — "download of report.pdf
+	 * cancelled", "dialog accepted". Never page text: the tool shows it
+	 * outside the untrusted envelope.
+	 */
+	readonly message?: string
+	readonly snapshot?: BrowserSnapshot
+	readonly screenshot?: BrowserScreenshot
+	readonly tabs?: readonly BrowserTabInfo[]
+}
+
+/** What a snapshot said about one ref, for labelling a call before it runs. */
+export interface BrowserRefDescription {
+	/** ARIA role: `button`, `link`, `textbox`. */
+	readonly role: string
+	/** Accessible name. Page-controlled. */
+	readonly name?: string
+}
+
+/** Who and where, for labels and reviews. May change between calls. */
+export interface BrowserSessionInfo {
+	/** The profile the browser runs under. */
+	readonly profile?: string
+	/** Canonical origin of the active tab, when the host knows it. */
+	readonly origin?: string
+}
+
+// ---------------------------------------------------------------------------
+// Structural errors. Hosts throw values carrying these shapes; the tools
+// recognise them by shape, so a separately installed host and SDK need not
+// share an error class.
+// ---------------------------------------------------------------------------
+
+/** The live page is not on the origin a `browser_act` call named. Nothing was done. */
+export interface BrowserOriginMismatch {
+	readonly code: 'browser_origin_mismatch'
+	readonly expected: string
+	readonly actual: string
+	readonly message: string
+}
+
+/** The ref is not on the current page: it came from an older snapshot. Nothing was done. */
+export interface BrowserStaleRef {
+	readonly code: 'browser_stale_ref'
+	readonly ref: string
+	readonly message: string
+}
+
+/** Why the page needs a person. */
+export type BrowserHumanRequiredReason =
+	| 'sign-in'
+	| 'two-factor'
+	| 'captcha'
+	| 'bot-block'
+	| 'http-auth'
+	| 'credential-field'
+
+/**
+ * The page needs a person: a sign-in, a second factor, a CAPTCHA, a bot
+ * wall, or a field that takes a password or one-time code. The agent must
+ * stop and hand over; it never signs in, solves or types a credential.
+ */
+export interface BrowserHumanRequired {
+	readonly code: 'browser_human_required'
+	readonly reason: BrowserHumanRequiredReason
+	readonly origin: string
+	readonly message: string
+	readonly profile?: string
+	/** The command that opens a visible window on this profile, e.g. `namzu browser login work https://…`. */
+	readonly loginCommand?: string
+}
+
+/**
+ * A page-changing action started and did not report a clean completion. The
+ * page may already have changed, so replaying it is unsafe.
+ */
+export interface BrowserOutcomeUnknown {
+	readonly code: 'browser_outcome_unknown'
+	readonly action: BrowserActionName
+	readonly outcome: 'unknown'
+	readonly retrySafety: 'unsafe'
+	readonly message: string
+}
+
+/** The site policy does not allow this origin at the level the call needs. */
+export interface BrowserSiteDenied {
+	readonly code: 'browser_site_denied'
+	readonly origin: string
+	readonly message: string
+}
+
+export type BrowserHostError =
+	| BrowserOriginMismatch
+	| BrowserStaleRef
+	| BrowserHumanRequired
+	| BrowserOutcomeUnknown
+	| BrowserSiteDenied
+
+// ---------------------------------------------------------------------------
+// Host
+// ---------------------------------------------------------------------------
+
+export interface BrowserCallOptions {
+	/** Fires when the call is cancelled or times out. */
+	readonly signal?: AbortSignal
+}
+
+/**
+ * A browser the tools drive. Implementations live outside `@namzu/sdk`.
+ *
+ * The host is where the site policy is enforced after the fact: whatever the
+ * gate approved, the host re-checks the page a navigation, redirect or popup
+ * actually landed on, and the live origin before every `act`.
+ */
+export interface BrowserHost {
+	readonly id: string
+	readonly capabilities: BrowserCapabilities
+
+	/** Observe or navigate. Throws a {@link BrowserHostError} shape to refuse. */
+	observe(action: BrowserObserveAction, options?: BrowserCallOptions): Promise<BrowserResult>
+	/**
+	 * Change the page. MUST check `action.origin` against the live page first
+	 * (see {@link BrowserActAction}). Throws a {@link BrowserHostError} shape
+	 * to refuse.
+	 */
+	act(action: BrowserActAction, options?: BrowserCallOptions): Promise<BrowserResult>
+
+	/**
+	 * What the most recent snapshot said about `ref`, synchronously and
+	 * without touching the page, for the label a person approves. Undefined
+	 * when the ref is unknown.
+	 */
+	describeRef?(ref: string): BrowserRefDescription | undefined
+	/** The current profile and page, synchronously, for labels. */
+	session?(): BrowserSessionInfo
+
+	initialize?(): Promise<void>
+	dispose?(): Promise<void>
+}

package/src/types/hitl/index.ts

@@ -40,6 +40,15 @@ export type HITLResumeDecision =
 			 * person said yes to a batch that showed the escape.
 			 */
 			confirmedEscalations?: readonly string[]
+			/**
+			 * Ids of calls approved on the strength of a skill's `allowed-tools`
+			 * grant ({@link ToolCallSummary.skillGrant}), with nobody asked.
+			 *
+			 * The kernel writes each one to the session's audit trail naming the
+			 * skill, and only for a call that actually carried the grant — an id
+			 * listed here for an unmarked call is ignored rather than trusted.
+			 */
+			skillGranted?: readonly string[]
 	  }
 	| {
 			action: 'modify_tools'
@@ -126,6 +135,18 @@ export interface ToolCallSummary {
 	 * approve it on their own. A `deny` rule still refuses it outright.
 	 */
 	escalation?: ToolCallEscalation
+	/**
+	 * Present when a skill loaded earlier in this turn pre-approved this call
+	 * through its `allowed-tools`, and nothing stronger stands in the way.
+	 *
+	 * Marked only on a call the operator's policy left to review (no `deny`,
+	 * no explicit `ask` rule), that is not destructive and that carries no
+	 * {@link escalation}. The review policy decides what the mark is worth:
+	 * `createReviewHandler` approves a batch without asking when every call
+	 * it would have asked about carries one, and still refuses under `plan`
+	 * and `strict`. A host's own handler may ignore it.
+	 */
+	skillGrant?: { readonly skill: string }
 }
 
 /** See {@link ToolCallSummary.escalation}. */

package/src/types/session/events.ts

@@ -534,6 +534,12 @@ type CoreSessionEvent =
 			providerError?: import('../provider/error.js').ProviderErrorInfo
 			/** Curated operator copy, absent when no catalog rule matched. */
 			explanation?: { id: string; message: string; hint: string }
+			/**
+			 * Present when a tool asked for a person: its `ToolResult.handoff`.
+			 * The results of the batch are already committed; resuming the turn
+			 * calls the model with them.
+			 */
+			handoff?: import('../tool/index.js').ToolHandoff
 	  }
 	/** A paused turn continues from its checkpoint, under the same `turnId`. */
 	| {

package/src/types/session/records.ts

@@ -201,6 +201,15 @@ const providerError = z
 
 const explanation = z.object({ id: text, message: text, hint: text }).strict()
 
+/** A tool's request for a person, as `turn_paused` carries it. */
+const toolHandoff = z
+	.object({
+		kind: z.literal('human-required'),
+		reason: text,
+		detail: z.record(text).optional(),
+	})
+	.strict()
+
 const stopReason = z.enum([
 	'end_turn',
 	'token_budget',
@@ -361,6 +370,7 @@ export const TurnPausedRecordSchema = inTurn('turn_paused', {
 	providerError: providerError.optional(),
 	explanation: explanation.optional(),
 	budget: tokenBudgetSummary.optional(),
+	handoff: toolHandoff.optional(),
 })
 
 export const TurnResumingRecordSchema = inTurn('turn_resuming', {

package/src/types/tool/index.ts

@@ -77,6 +77,8 @@ export interface SkillRegistryRef {
 						invocation?: 'model' | 'operator' | 'both'
 					}
 					body?: string
+					/** The skill's directory, which `${CLAUDE_SKILL_DIR}` in `allowed-tools` names. */
+					dirPath?: string
 				}
 		  }
 		| undefined
@@ -473,18 +475,56 @@ export interface ToolContext {
 	}
 
 	/**
-	 * Adopt the tool scope a skill declared.
+	 * Formerly: narrow the turn's tools to what a skill's `allowed-tools`
+	 * named. That reading was backwards — the field pre-approves, it never
+	 * restricts — and the kernel no longer supplies this member, so a tool
+	 * that calls it through `?.` does nothing.
 	 *
-	 * Called by the `skill` tool when a loaded skill names `allowed-tools`.
-	 * The scope INTERSECTS what the turn already allows and takes effect from
-	 * the next batch — a skill loaded alongside other calls must not
-	 * retroactively refuse them.
+	 * @deprecated Never supplied by the kernel since `allowed-tools` became a
+	 * pre-approval. Use {@link ToolContext.grantSkillTools}. Removed in the
+	 * next major.
 	 */
 	adoptSkillScope?: (scope: {
 		skill: string
 		allowedTools: readonly string[]
 	}) => void
 
+	/**
+	 * Pre-approve what a loaded skill's `allowed-tools` names, for the rest of
+	 * this turn.
+	 *
+	 * Called by the `skill` tool. It never narrows anything: every tool the
+	 * turn had stays callable, and a call the grant does not cover is reviewed
+	 * exactly as before. A covered call skips the approval prompt, but not an
+	 * operator `deny` or `ask` rule, plan mode, `strict` mode, a destructive
+	 * call or one that reaches outside the turn's roots or sandbox. Each call
+	 * approved this way is written to the session's audit trail naming the
+	 * skill.
+	 *
+	 * Returns what would be granted and what was ignored (an unknown tool
+	 * name, a pattern on a tool without a command line, a tool every call of
+	 * which is destructive), so the tool can tell the model. Nothing is
+	 * recorded until `commit()` is called: the caller commits only once the
+	 * skill's instructions have actually been delivered, so a load that fails
+	 * afterwards leaves no approval behind. Absent outside a turn, where
+	 * there is nothing to grant into.
+	 */
+	grantSkillTools?: (grant: {
+		readonly skill: string
+		/** The parsed entries, as `parseAllowedTools` returns them. */
+		readonly allowedTools: readonly string[]
+		/** The skill's directory, for `${CLAUDE_SKILL_DIR}` / `${NAMZU_SKILL_DIR}`. */
+		readonly skillDirectory?: string
+	}) => {
+		readonly granted: readonly string[]
+		readonly ignored: readonly {
+			readonly entry: string
+			readonly reason: string
+		}[]
+		/** Record the grant in the turn. Idempotent. */
+		readonly commit: () => void
+	}
+
 	/**
 	 * Effective model-visible character cap for this tool result.
 	 *
@@ -675,8 +715,41 @@ export interface ToolResult {
 	 * must not lose: what its controls do, where things are, what failed.
 	 */
 	workingState?: readonly import('../../compaction/types.js').WorkingStatePin[]
+	/**
+	 * This result needs a person before the turn can go on — a sign-in page,
+	 * a CAPTCHA, a second factor, anything the model must not try to answer
+	 * itself.
+	 *
+	 * The result is committed like any other: it reaches the transcript and
+	 * the session log with the rest of its batch. Then, instead of calling
+	 * the model again, the kernel writes a checkpoint and ends the segment
+	 * with `turn_paused` carrying this value. Resuming the turn continues
+	 * from that checkpoint, and the next step is a model call that sees the
+	 * results. Inside a delegated child there is no person to hand to, so
+	 * the child's turn fails with {@link ToolHandoff.reason} instead.
+	 */
+	handoff?: ToolHandoff
 }
 
+/**
+ * A tool's request to stop the turn for a person. See {@link ToolResult.handoff}.
+ */
+export interface ToolHandoff {
+	readonly kind: 'human-required'
+	/** Operator-facing text: what the person has to do before the turn resumes. */
+	readonly reason: string
+	/** Structured facts a host can render or act on, such as an origin or a command. */
+	readonly detail?: Readonly<Record<string, string>>
+}
+
+/**
+ * The shell a command line will run in, as the permission rules read it.
+ * `bash` reads it as bash does. `sh` reads it for a shell that may be bash or
+ * a POSIX shell such as `dash`: every construct the two read differently
+ * makes the line opaque, so a line that is not opaque means the same in both.
+ */
+export type ShellDialect = 'bash' | 'sh'
+
 export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {
 	name: string
 	description: string
@@ -737,6 +810,20 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * chaining — has nothing to decompose and must not claim otherwise.
 	 */
 	commandArgument?: string
+	/**
+	 * The shell {@link commandArgument} runs in, as the dialect the permission
+	 * rules must read it in.
+	 *
+	 * A rule reads a command line before it runs, and the reading is only
+	 * right for the shell that runs it: `$'\x3b'`, `|&` and `&>` mean one
+	 * thing to bash and another to `dash`. `bash` reads the line as bash
+	 * does. `sh`, the default when this is absent, reads it for a shell that
+	 * may be bash or a POSIX shell, and every construct the two read
+	 * differently makes the line opaque, so no allow rule approves it. The
+	 * shipped `bash` tool answers `bash` when it will spawn bash on the host
+	 * and `sh` inside a sandbox, whose guest may not have bash.
+	 */
+	commandDialect?: (context: { readonly sandboxed: boolean }) => ShellDialect
 	/**
 	 * The argument that holds a filesystem path the tool resolves against the
 	 * turn's roots (the working directory and the added directories).
@@ -748,6 +835,23 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * the safe direction to be wrong in.
 	 */
 	pathArgument?: string
+	/**
+	 * The argument that holds an absolute URL the tool has already
+	 * canonicalised in its input schema — one spelling, no whitespace.
+	 *
+	 * Declared so an `argument_pattern` rule tests the URL whole. Without it
+	 * the rule reads every argument as a possible command line, and a URL's
+	 * query separators (`&`, `;`, `|`) cut it into "segments": an `allow` for
+	 * `^https://github\.com(?:[/?#]|$)` then declined
+	 * `https://github.com/search?q=a&type=code`, because `type=code` is not
+	 * GitHub. A `deny` or `review` is unaffected either way; only an `allow`
+	 * needed every segment to match.
+	 *
+	 * Declare it only for an argument the input schema itself canonicalises
+	 * to a URL. A free-text argument that happens to hold one keeps the
+	 * command-line reading, which is the safe direction to be wrong in.
+	 */
+	urlArgument?: string
 	/**
 	 * The boolean argument by which a call asks to run outside the turn's
 	 * sandbox, when the tool offers that at all (the shipped `bash` does).

package/src/types/tool/presentation.ts

@@ -26,6 +26,13 @@ export type ToolCallView =
 			readonly activity?: 'exploration'
 			/** A successful result may add no information beyond the completed call row. */
 			readonly visibility?: 'hidden'
+			/**
+			 * For a result: the person declined on the tool's own screen (a
+			 * confirmation they cancelled). The call did not succeed, but
+			 * nothing failed either, so a host draws it as neither: `label` says
+			 * what did not happen ("Cancelled — nothing was saved").
+			 */
+			readonly outcome?: 'cancelled'
 	  }
 	/**
 	 * A change to a document. `path` is optional because not every diff is